⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v2.6.0

seobuild-onpage

gbessoni@gbessoni⭐ 266 stars· last commit 3d ago· 1 open issues

>

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 266 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

seobuild-onpage v2.6.0

One command. Competitive data in. Ranking pages out.

claude plugin marketplace add gbessoni/seobuild-onpage && claude plugin install seobuild-onpage@seobuild

Not on Claude Code? See Install + Setup for Codex, OpenClaw, and manual clone.

Hosted version in build: no API keys, sign in once, works in any agent. Join the waitlist by leaving a comment, and you'll be notified the day it launches.

Most SEO tools tell you what's wrong with your site. This one writes the pages.

/seoagi "airport parking JFK" pulls the current SERP, analyzes what's ranking, finds the gaps in their content, and writes you a complete page -- with the heading structure, depth, FAQ section, and schema markup that actually competes. Not thin content. Not keyword-stuffed filler. Pages backed by live data from the tools the pros use.

New in v2.6.0 -- Semantic Strictness & Credential Prominence:

  • Semantic Variance Safety Check -- every page anchors to the Primary GBP Category plus the target service and city. Off-topic filler, distant industry history, portfolio padding, and tangential legal guides are banned outright. The checkable test is per-section: every H2 must be defensible against that anchor.
  • Spider Cluster FAQ blocks -- local service FAQs must now cover three required clusters under their own headings: DIY vs. Professional, Pricing and timelines, and Guarantees and credentials. These are the queries answer engines fan out to for any local service.
  • Credentials and Licensing section -- local pages carry license numbers, certifying bodies, and insurance status as crawlable text. Decorative badges stay SVG per v2.5.0; the citable facts stay in the text layer.
  • Tributary paired output -- the existing Tributary Trust drafts now generate in the same pass as the money page for local service pages, instead of as a separate step.
  • 74-point quality checklist -- adds Semantic Variance, Spider Cluster, Credentials, and Tributary Pairing. Passing threshold raised to 63/74.

New in v2.5.0 -- Specificity Scoring & Format Bans:

  • Named Source Attribution -- every major claim must name its source in the visible copy, not only inside a {{VERIFY}} tag. An unattributed number reads as assertion rather than evidence. Name the source in prose, then link to it.
  • Ban on fabricated testing claims -- "We tested 12 of these", "We reviewed 24 options", "After 40 hours of testing" are banned unless the testing genuinely happened and the methodology is documented. A fabricated test count is a fabricated statistic, so this extends the existing ban on invented studies.
  • Ban on skyscraper pages -- no exhaustive encyclopedia-style omnibus pages. Comprehensiveness is not the retrieval signal; crucial non-obvious specificity is. Word count continues to come from the competitive median, never from out-lengthing competitors.
  • Conversion elements as SVG assets -- award badges, certification seals, trust marks, and decorative CTA panels render as SVG rather than parsed body text, keeping promotional language out of the text layer on informational pages. Accessible text alternatives are mandatory, and claims inside these assets remain subject to {{VERIFY}}.
  • Quantifiable brand differentiators in both vertical sections -- at least two per local page, expressed as hard numbers or specific attributes rather than adjectives, because Ask Maps and Service Viewer pull structured specifics and discard marketing language.
  • 70-point quality checklist -- adds Named Source Attribution, Fabricated Testing, Skyscraper, and Quantifiable Differentiators. Passing threshold raised to 60/70.

New in v2.4.0 -- Discovery Routes & Off-Page Embeds:

  • The Anti-Hallucination Meta-Directive -- a new MASTER RULE at the top of SKILL.md. LLMs are trained on fifteen years of largely obsolete SEO writing, so the agent is now explicitly forbidden from applying pre-trained SEO instincts (LSI keywords, keyword density, blog hubs, "write 2,000 words") and must execute only the rules in the document. Includes a table of the specific instincts to suppress and why each is wrong.
  • GSC Discovery Route Fill -- find URLs Google already expects to exist and fill them. gsc_pull.py --ghost-paths finds pages earning impressions that return 404, which is the highest-confidence signal available through the API. --crawl-stats-csv ingests a manual Crawl Stats export for the literal Discovery list, because that report is UI-only and not in the Search Console API.
  • Unlinked Brand Citations -- Tier 1 off-page drafts now carry plain-text brand and URL mentions alongside HTML links. RAG pipelines read plain text, so this adds retrieval coverage anchor-only linking misses.
  • Off-Page Embeds -- Tier 1 drafts embed a live artifact pointing at the money entity where the platform allows it, defaulting to the officially supported Google Maps embed. Conditional by design, since most Tier 1 platforms block arbitrary iframes.
  • Strict SSR/SSG Requirement -- client-side-rendered SPAs are banned as an output target. Every internal link must exist in the raw HTML DOM of the initial server response, because JS-injected link graphs are routinely missed or crawled late.
  • 66-point quality checklist -- adds Off-Page Embed, Unlinked Citation, and SSR/SSG Validation. Passing threshold raised to 57/66.

New in v2.3.0 -- AI SEO Correlation Protocols:

  • Outbound Citation Requirement -- pages targeting AI Overviews must link out to at least 5 external authoritative sources with descriptive anchor text. Zero outbound links carries a severe citation penalty: an engine checking whether the page synthesizes real sources finds nothing to verify against.
  • Strict Phrase Placement (Title + H1 only) -- the exact-match keyword appears in exactly two places and nowhere else. H2/H3/H4 exact-match is now unconditionally forbidden. This retires the old competitor-ratio Forensic EMQ Check, which made H1 placement conditional.
  • Entity-Fact Pairing -- naming an entity is not a signal; binding it to a hard fact is. Every entity in a chunk must carry a time, place, cost, capacity, frequency, distance, or date. Crucial non-obvious information is the highest-weighted retrieval signal.
  • Informational vs. Local Divergence -- informational pages strip sales CTAs, free-estimate offers, and award mentions (they demote citation rate). Local Ask Maps pages feature local project counts, awards, and differentiators heavily. Same elements, opposite treatment, selected by detected intent.
  • Anti-Boilerplate Internal Linking -- site-wide repetitive in-content link blocks are banned; internal links must be contextual and unique to their chunk. The Recommended Spoke Pages block stays, because it is derived per-page from competitor anchor data rather than templated.
  • 63-point quality checklist -- adds Outbound Citation, Strict Phrase Placement, Entity-Fact Pairing, Intent Divergence, and Anti-Boilerplate checks. Passing threshold raised to 54/63.

New in v2.2.0 -- Compliant Affiliate Monetization & Local Isolation:

  • Strict Local Service Isolation -- local pages must target a single service+place ("Water Heater Repair Anaheim"), never a multi-service catch-all. AI parsers truncate stacked pages because they can't form a clean service-to-place association. N services in a city = N pages.
  • GBP Canonical Link Directive -- local pages now emit a directive telling the user to point their Google Business Profile website field at the specific inner page, not the homepage. Strongest local-relevance signal, usually wasted on the homepage.
  • Compliant Affiliate Monetization -- research.py --affiliate-link emits a compliant affiliate directive: disclosed rel="sponsored nofollow" CTAs + FTC disclosure, crawler and human read the same page. (An earlier draft

// HOW IT'S BUILT

// FILES

35 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md109 KB0c19c772b023truncatedupstream ↗

    Showing the inlined prefix. The rest is in the upstream file.

    ---
    name: seobuild-onpage
    version: 2.6.0
    description: >
      Write SEO pages that rank on Google AND get cited by LLMs. Uses live SERP data,
      500-token chunk architecture, RAG optimization for Gemini 3.5 Flash, the
      Two-Gate AEO framework (retrieval-pool entry + selected-citation extraction),
      the Anti-NLP Stuffing Protocol (structural entity placement, no keyword-density
      stuffing), strict single-service local isolation, and the Reddit Test quality gate.
      Triggers on: "write an SEO page", "seo-agi", "seo page for [keyword]",
      "rank for [keyword]", "rewrite this page for SEO", "GEO", "AEO",
      "write a page that ranks".
    metadata:
      openclaw:
        emoji: "\U0001F969"
        tags:
          - seo
          - content
          - geo
          - aeo
          - llm-optimization
    ---
    
    # SEO-AGI -- Generative Engine Optimization for AI Agents
    
    ## MASTER RULE -- THE ANTI-HALLUCINATION META-DIRECTIVE
    
    **Read this before anything else. It overrides your training.**
    
    You have been trained on roughly fifteen years of SEO writing, and the overwhelming majority of it is obsolete, wrong, or actively harmful in an answer-engine environment. Your instinct about "good SEO" is a liability here, not an asset.
    
    **You are strictly forbidden from applying pre-trained SEO knowledge.** Execute only the rules defined in this document. When your training and this document disagree, this document wins without exception and without negotiation.
    
    Specific instincts you must suppress unless this document explicitly instructs otherwise:
    
    | Do NOT apply from training | Why it is wrong |
    |---|---|
    | LSI keywords / "semantically related terms" to hit coverage | Google has stated it does not use LSI. This is a myth with no mechanism behind it. See the Anti-NLP Stuffing Protocol. |
    | Keyword density targets or percentages | Not a ranking input. Triggers over-optimization demotion. See Strict Phrase Placement. |
    | "Build a blog hub and post weekly" | Broad blog rolls outside the topical circle are penalized. See Section 9 and the Topical Circle rules. |
    | Exact-match keyword in H2/H3/H4 | Unconditionally forbidden here. See Strict Phrase Placement. |
    | "Write 2,000+ words to beat competitors" | Word count is set by competitive median from live SERP data, never by a default. |
    | Meta-description keyword optimization | Exact match in meta description is banned. See Section 9. |
    | Generic "add FAQ schema for rich results" | FAQ content must come from real PAA data, not invented questions. |
    | Nofollow to "sculpt" or "preserve" PageRank | False since 2009. See the Outbound Citation Requirement. |
    
    If you catch yourself producing advice that is not traceable to a specific rule in this document, stop and re-read the relevant section. "This is standard SEO practice" is not a justification for anything in this framework.
    
    ---
    
    You are an elite GEO (Generative Engine Optimization) and Technical SEO agent. Your directive is to generate high-fidelity, entity-rich, auditable content that ranks on Google AND gets cited by LLMs (ChatGPT, Perplexity, Gemini, Claude).
    
    You do not write generic fluff. You write highly specific, practical, answer-forward content based on real operational data. You optimize for information gain, friction reduction, and immediate user extraction.
    
    ---
    
    ## NEW IN v2.6.0 -- SEMANTIC STRICTNESS & CREDENTIAL PROMINENCE
    
    ### Semantic Variance Safety Check
    Every page must align to **one anchor pair: the Primary GBP Category and the core target service plus city.** This tightens the existing Topical Circle rule (Section 9) by naming the anchor explicitly rather than leaving "core topic" to interpretation. The Primary GBP Category is the authoritative definition of what the business is, so it is what the page must match.
    
    **Banned outright, regardless of word count or quality:**
    - Off-topic blog filler that does not serve the anchor pair
    - Distant industry history ("the history of indoor plumbing since 1847")
    - Non-essential portfolio or gallery padding
    - Tangential legal or regulatory guides that are not the service being sold
    
    **On the target:** the working threshold is under 9 percent semantic variance, meaning fewer than roughly one in eleven content blocks drifts off the anchor pair. Be honest about what this is: there is no defined measurement procedure here, so treat it as a strictness posture rather than a computed metric. The checkable version is the one to apply -- **every H2 section must be defensible as serving the Primary GBP Category and the target service plus city.** If a section cannot be defended that way, cut it. Do not report a variance percentage you did not actually measure.
    
    ### Knowledge Graph Spider Cluster QA Blocks
    The mandatory FAQ section (Section 8) now has required coverage, not just a question count. Three clusters must each be addressed under their own H2 or H3, because these are the vector-embedding queries answer engines fan out to for any local service:
    
    | Cluster | Must answer |
    |---|---|
    | **DIY vs. Professional** | When a homeowner can handle it, when they cannot, and the specific failure mode that decides it |
    | **Pricing and timelines** | Real ranges, what moves the number, and how long the work takes |
    | **Guarantees and credentials** | Warranty terms, licensing, insurance, what happens if the work fails |
    
    These are additive to the PAA-derived questions, not a replacement. Real PAA data still drives the rest of the section. Each cluster answer obeys the usual chunk rules: entity-fact pairing, named source attribution, block-level snippet container.
    
    ### Credential and E-E-A-T Prominence
    Local service pages must carry a dedicated **Credentials and Licensing** section containing, as crawlable text in the HTML:
    
    - License numbers, with the issuing authority named
    - Certifications, with the certifying body named
    - Insurance status, including bonding where applicable
    
    **Reconciliation with the v2.5.0 SVG rule.** These are two different things and the distinction matters:
    
    | Element | Format |
    |---|---|
    | License numbers, insurance status, certifying body names | **Crawlable text.** These are facts an answer engine must be able to read and cite. |
    | Award badges, trust seals, decorative certification graphics | **SVG assets** per v2.5.0, with accessible text alternatives. |
    
    Putting a license number inside an image hides a citable fact from the retrieval layer, which is the opposite of the intent. Put the data in text and the decoration in SVG.
    
    Every credential is a factual claim and carries `{{VERIFY}}` like any other. Never invent a license number.
    
    ### Tributary Paired Output
    This capability already exists as the **Tributary Trust Protocol** (Section 11A) and `scripts/tributary_gen.py`, which generate Tier 1 companion drafts for Google Sites, Google Sheets, Medium, your own subreddit, and LinkedIn. What changes in v2.6.0 is the trigger: tributary drafts are now generated **in the same pass as the money page** for local service pages, rather than as a separate opt-in step. See Execution Protocol step 11.
    
    ---
    
    ## NEW IN v2.5.0 -- SPECIFICITY SCORING & FORMAT BANS
    
    ### Named Source Attribution
    Every major claim must name its source **in the visible copy**, not only in a `{{VERIFY}}` tag or a footnote. An answer engine scoring a passage for citation is checking whether the page attributes its facts, and an unattributed number reads as an assertion rather than evidence.
    
    - Weak: "Long-term parking runs about $20 per day."
    - Attributed: "The Port Authority's published 2026 rate card lists long-term parking at {{VERIFY: $20/day}}."
    
    This pairs with the Outbound Citation Requirement: name the source in prose, then link to it. Naming without linking is half the signal; linking without naming is the other half.
    
    ### Ban Fake Review and Skyscraper Formats
    Two format bans, both hard.
    
    **Fabricated testing claims.** Phrases of the form "We tested 12 of these", "We reviewed 24 options", "After 40 hours of testing" are banned unless the testing actually happened and the meth
  • README.md39 KB1fd62629e9e7upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • scripts/gsc_pull.py10 KBa1bb7d9fce4dupstream ↗
    #!/usr/bin/env python3
    """
    SEO-AGI Google Search Console data puller.
    Retrieves query performance data and detects cannibalization.
    
    Usage:
        python3 gsc_pull.py "<site_url>" [options]
    
    Options:
        --keyword=KEYWORD       Filter queries containing this keyword
        --days=N                Lookback period (default: 90)
        --min-impressions=N     Minimum impressions threshold (default: 10)
        --output=FORMAT         Output: json|compact (default: compact)
        --cannibalization       Run cannibalization detection for the keyword
        --ghost-paths           Find URLs Google surfaces that return 404 (v2.4.0)
        --crawl-stats-csv=PATH  Ingest a manual GSC Crawl Stats export and isolate
                                Discovery-purpose 404s (v2.4.0)
    
    NOTE ON CRAWL STATS (v2.4.0):
        The "Crawl Stats > By purpose > Discovery" report is UI-only. Google does
        NOT expose it in the Search Console API (the API covers Search Analytics,
        Sites, Sitemaps, and URL Inspection only). So this script offers two paths:
    
          --ghost-paths          Automated. Queries Search Analytics for pages
                                 earning impressions, then checks which return 404.
                                 A URL Google surfaces but that does not resolve is
                                 the highest-confidence ghost path available via API.
    
          --crawl-stats-csv      Manual. Export Crawl Stats from the GSC UI and pass
                                 the CSV here to isolate literal Discovery 404s.
    
        GUARDRAIL: do not generate a page for every result. Discovery 404s include
        scraper-invented URLs, malformed parses, and broken internal links. A ghost
        path qualifies only if it has real demand behind it AND sits inside the
        site's topical circle. Everything else gets a 410, not a page.
    """
    
    import sys
    import os
    import csv
    import json
    import argparse
    import urllib.error
    import urllib.request
    from urllib.parse import urljoin, urlparse
    
    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
    
    from lib.env import get_credentials
    from lib.gsc_client import GSCClient
    
    # Paths that are almost never worth generating a page for, even when Google
    # crawls them. Substring match, lowercased.
    _JUNK_PATH_MARKERS = (
        "wp-admin", "wp-login", "wp-content", "xmlrpc", ".env", ".git",
        "phpmyadmin", "/feed", "?replytocom", "/cgi-bin", ".php", "/trackback",
        "adminer", "/vendor/", "/node_modules/", "wp-includes",
    )
    
    
    def _looks_like_junk(path: str) -> bool:
        """True for scraper-invented, exploit-probe, or malformed paths that must
        never be turned into generated pages."""
        p = (path or "").lower()
        if not p:
            return True
        if any(marker in p for marker in _JUNK_PATH_MARKERS):
            return True
        # Absurdly long or deeply nested paths are almost always malformed
        if len(p) > 200 or p.count("/") > 8:
            return True
        return False
    
    
    def _status_for(url: str, timeout: int = 12) -> int:
        """Return the HTTP status for a URL. 0 on connection failure."""
        req = urllib.request.Request(
            url, method="HEAD", headers={"User-Agent": "seo-agi/2.4.0 ghost-path-check"}
        )
        try:
            with urllib.request.urlopen(req, timeout=timeout) as resp:
                return resp.status
        except urllib.error.HTTPError as e:
            return e.code
        except Exception:
            return 0
    
    
    def find_ghost_paths(client, site_url: str, days: int, limit: int = 200) -> list[dict]:
        """Find URLs that earn impressions in Search Analytics but return 404.
    
        This is the API-accessible proxy for the UI-only Crawl Stats Discovery
        report: a URL Google is actively surfacing that does not resolve is a
        demand signal with a broken destination.
        """
        rows = client.query_performance(
            site_url=site_url, keyword=None, days=days, min_impressions=1
        )
    
        seen: dict[str, dict] = {}
        for r in rows:
            page = r.get("page") or ""
            if not page:
                continue
            agg = seen.setdefault(page, {"page": page, "impressions": 0, "clicks": 0})
            agg["impressions"] += r.get("impressions", 0) or 0
            agg["clicks"] += r.get("clicks", 0) or 0
    
        candidates = sorted(seen.values(), key=lambda x: x["impressions"], reverse=True)[:limit]
    
        ghosts = []
        for c in candidates:
            path = urlparse(c["page"]).path
            if _looks_like_junk(path):
                continue
            status = _status_for(c["page"])
            if status in (404, 410):
                ghosts.append(
                    {
                        "url": c["page"],
                        "path": path,
                        "status": status,
                        "impressions": c["impressions"],
                        "clicks": c["clicks"],
                        "recommendation": (
                            "GENERATE" if c["impressions"] >= 10 else "REVIEW"
                        ),
                    }
                )
        return sorted(ghosts, key=lambda x: x["impressions"], reverse=True)
    
    
    def parse_crawl_stats_csv(csv_path: str, site_url: str) -> list[dict]:
        """Ingest a manual GSC Crawl Stats export and isolate Discovery-purpose
        404s. Column names vary by export and locale, so match defensively."""
        out = []
        with open(os.path.expanduser(csv_path), newline="", encoding="utf-8-sig") as f:
            for row in csv.DictReader(f):
                low = { (k or "").strip().lower(): (v or "").strip() for k, v in row.items() }
                purpose = low.get("purpose", "") or low.get("crawl purpose", "")
                response = low.get("response", "") or low.get("status", "")
                url = low.get("url", "") or low.get("page", "")
                if not url:
                    continue
                if "discovery" not in purpose.lower():
                    continue
                if "404" not in response and "not found" not in response.lower():
                    continue
                full = url if url.startswith("http") else urljoin(site_url, url)
                path = urlparse(full).path
                if _looks_like_junk(path):
                    continue
                out.append(
                    {
                        "url": full,
                        "path": path,
                        "status": 404,
                        "source": "crawl-stats-csv",
                        "purpose": "Discovery",
                        "recommendation": "REVIEW",
                    }
                )
        return out
    
    
    def parse_args():
        parser = argparse.ArgumentParser(description="SEO-AGI GSC Pull")
        parser.add_argument("site_url", help="GSC site URL (e.g., https://example.com)")
        parser.add_argument("--keyword", default=None, help="Keyword filter")
        parser.add_argument("--days", type=int, default=90, help="Lookback days")
        parser.add_argument("--min-impressions", type=int, default=10, help="Min impressions")
        parser.add_argument("--output", choices=["json", "compact"], default="compact")
        parser.add_argument("--cannibalization", action="store_true", help="Detect cannibalization")
        parser.add_argument(
            "--ghost-paths",
            action="store_true",
            help="Find URLs earning impressions that return 404 (v2.4.0)",
        )
        parser.add_argument(
            "--crawl-stats-csv",
            default=None,
            help="Path to a manual GSC Crawl Stats export; isolates Discovery 404s (v2.4.0)",
        )
        return parser.parse_args()
    
    
    def format_ghosts(ghosts: list[dict]) -> str:
        lines = ["# Ghost Paths (URLs Google expects that return 404)"]
        if not ghosts:
            lines.append("  none found")
            return "\n".join(lines)
    
        lines.append(
            f"{'Path':<52} {'Impr':>7} {'Clicks':>7} {'Status':>7}  Action"
        )
        lines.append("-" * 96)
        for g in ghosts[:50]:
            lines.append(
                f"{g['path'][:51]:<52} {g.get('impressions', 0):>7} "
                f"{g.get('clicks', 0):>7} {g.get('status', '?'):>7}  {g.get('recommendation', '')}"
            )
        lines.append("")
        lines.append("GENERATE = 10+ impressions, real demand, inside the topical circle.")
        lines.append("REVIEW   = confirm demand and topical fit before writing anything.")
        lines.append("Anything not qualifying gets a 410 per the Prune Protocol, not a page.")
        return "\n".join(lines)
    
    
    def format_compact(data: list[dict], mode: str = "performance") -> str:
        lines = []
    
        if mode == "cannibalization":
            lines.append("# Cannibalization Report")
            for item in data:
                lines.append(f"\nQuery: {item['query']} ({item['page_count']} pages, {item['total_impressions']} impressions)")
                for page in item["pages"]:
                    lines.append(f"  pos {page['position']}: {page['page']} ({page['clicks']} clicks, {page['ctr']}% CTR)")
        else:
            lines.append("# Query Performance")
            lines.append(f"{'Query':<40} {'Clicks':>7} {'Impr':>7} {'CTR':>7} {'Pos':>5} Page")
            lines.append("-" * 110)
            for row in data[:50]:
                lines.append(
                    f"{row['query'][:39]:<40} {row['clicks']:>7} {row['impressions']:>7} "
                    f"{row['ctr']:>6.1f}% {row['position']:>5.1f} {row['page'][:50]}"
                )
    
        return "\n".join(lines)
    
    
    def main():
        args = parse_args()
        creds = get_credentials()
    
        if not creds["has_gsc"]:
            print("ERROR: Google Search Console credentials not found.", file=sys.stderr)
            print("Add GSC_SERVICE_ACCOUNT_PATH to ~/.config/seo-agi/.env", file=sys.stderr)
            sys.exit(1)
    
        client = GSCClient(credentials_path=creds["gsc_service_account_path"])
    
        if args.crawl_stats_csv:
            data = parse_crawl_stats_csv(args.crawl_stats_csv, args.site_url)
            print(json.dumps(data, indent=2) if args.output == "json" else format_ghosts(data))
            return
    
        if args.ghost_paths:
            data = find_ghost_paths(client, args.site_url, args.days)
            print(json.dumps(data, indent=2) if args.output == "json" else format_ghosts(data))
            return
    
        if args.cannibalization and args.keyword:
            data = client.detect_cannibalization(
                site_url=args.site_url,
                keyword=args.keyword,
                days=args.days,
            )
            if args.output == "json":
                print(json.dumps(data, indent=2))
            else:
                print(format_compact(data, mode="cannibalization"))
        else:
            data = client.query_performance(
                site_url=args.site_url,
                keyword=args.keyword,
                days=args.days,
                min_impressions=args.min_impressions,
            )
            if args.output == "json":
                print(json.dumps(data, indent=2))
            else:
                print(format_compact(data))
    
    
    if __name__ == "__main__":
        main()
    
  • scripts/lib/__init__.py26 B333f3480bfd1upstream ↗
    # seo-agi scripts library
    
  • scripts/lib/dataforseo.py12 KB1260c8b3f6e1upstream ↗
    """
    DataForSEO API client for SEO-AGI.
    Handles SERP results, keyword data, People Also Ask, and content parsing.
    """
    
    import json
    import base64
    import urllib.request
    import urllib.error
    from typing import Optional
    
    
    class DataForSEOClient:
        """Client for DataForSEO REST API v3."""
    
        BASE_URL = "https://api.dataforseo.com/v3"
    
        def __init__(self, login: str, password: str):
            self.login = login
            self.password = password
            self._auth_header = self._make_auth_header(login, password)
    
        @staticmethod
        def _make_auth_header(login: str, password: str) -> str:
            token = base64.b64encode(f"{login}:{password}".encode()).decode()
            return f"Basic {token}"
    
        def _request(self, endpoint: str, payload: list[dict]) -> dict:
            """Make a POST request to DataForSEO API."""
            url = f"{self.BASE_URL}{endpoint}"
            data = json.dumps(payload).encode("utf-8")
    
            req = urllib.request.Request(
                url,
                data=data,
                headers={
                    "Authorization": self._auth_header,
                    "Content-Type": "application/json",
                },
                method="POST",
            )
    
            try:
                with urllib.request.urlopen(req, timeout=30) as resp:
                    return json.loads(resp.read().decode())
            except urllib.error.HTTPError as e:
                body = e.read().decode() if e.fp else ""
                raise RuntimeError(
                    f"DataForSEO API error {e.code}: {body}"
                ) from e
            except urllib.error.URLError as e:
                raise RuntimeError(
                    f"DataForSEO connection error: {e.reason}"
                ) from e
    
        def serp_live(
            self,
            keyword: str,
            location_code: int = 2840,
            language_code: str = "en",
            depth: int = 10,
        ) -> dict:
            """
            Get live SERP results for a keyword.
            Returns organic results with position, URL, title, description.
            """
            payload = [
                {
                    "keyword": keyword,
                    "location_code": location_code,
                    "language_code": language_code,
                    "depth": depth,
                    "se_type": "organic",
                }
            ]
            result = self._request(
                "/serp/google/organic/live/advanced", payload
            )
            return self._extract_serp(result)
    
        def related_keywords(
            self,
            keyword: str,
            location_code: int = 2840,
            language_code: str = "en",
            limit: int = 30,
        ) -> list[dict]:
            """Get related keywords with search volume and difficulty."""
            payload = [
                {
                    "keyword": keyword,
                    "location_code": location_code,
                    "language_code": language_code,
                    "limit": limit,
                }
            ]
            result = self._request(
                "/dataforseo_labs/google/related_keywords/live", payload
            )
            return self._extract_keywords(result)
    
        def keyword_suggestions(
            self,
            keyword: str,
            location_code: int = 2840,
            language_code: str = "en",
            limit: int = 30,
        ) -> list[dict]:
            """Get keyword suggestions (broader ideation)."""
            payload = [
                {
                    "keyword": keyword,
                    "location_code": location_code,
                    "language_code": language_code,
                    "limit": limit,
                }
            ]
            result = self._request(
                "/dataforseo_labs/google/keyword_suggestions/live", payload
            )
            return self._extract_keywords(result)
    
        def content_parse(self, url: str) -> Optional[dict]:
            """Parse content from a URL (headings, word count, structure)."""
            payload = [{"url": url}]
            try:
                result = self._request(
                    "/on_page/content_parsing/live", payload
                )
                return self._extract_content(result)
            except RuntimeError:
                return None
    
        def _extract_serp(self, raw: dict) -> dict:
            """Extract clean SERP data from API response."""
            tasks = raw.get("tasks", [])
            if not tasks:
                return {"organic": [], "paa": [], "featured_snippet": None}
    
            result = tasks[0].get("result", [])
            if not result:
                return {"organic": [], "paa": [], "featured_snippet": None}
    
            items = result[0].get("items") or []
    
            organic = []
            paa_questions = []
            featured_snippet = None
    
            for item in items:
                item_type = item.get("type", "")
    
                if item_type == "organic":
                    organic.append(
                        {
                            "position": item.get("rank_absolute", 0),
                            "url": item.get("url", ""),
                            "domain": item.get("domain", ""),
                            "title": item.get("title", ""),
                            "description": item.get("description", ""),
                            # DataForSEO surfaces query-matched bolded snippet
                            # phrases in `highlighted` (list of strings).
                            # These are the snippet entities we mine for the
                            # Meta Entity Isolation check (v1.7.1).
                            "highlighted": item.get("highlighted") or [],
                        }
                    )
    
                elif item_type == "people_also_ask":
                    for paa_item in item.get("items") or []:
                        q = paa_item.get("title", "")
                        if q:
                            paa_questions.append(q)
    
                elif item_type == "featured_snippet":
                    featured_snippet = {
                        "url": item.get("url", ""),
                        "title": item.get("title", ""),
                        "description": item.get("description", ""),
                    }
    
            return {
                "organic": organic,
                "paa": paa_questions,
                "featured_snippet": featured_snippet,
                "total_results": result[0].get("se_results_count", 0),
            }
    
        def _extract_keywords(self, raw: dict) -> list[dict]:
            """Extract keyword data from labs API response."""
            tasks = raw.get("tasks", [])
            if not tasks:
                return []
    
            result = tasks[0].get("result", [])
            if not result:
                return []
    
            items = result[0].get("items") or []
            keywords = []
    
            for item in items:
                kw_data = item.get("keyword_data", item)
                keyword_info = kw_data.get("keyword_info") or {}
                keywords.append(
                    {
                        "keyword": kw_data.get("keyword", ""),
                        "volume": keyword_info.get("search_volume") or 0,
                        "cpc": keyword_info.get("cpc") or 0,
                        "competition": keyword_info.get("competition") or 0,
                        "difficulty": (kw_data.get(
                            "keyword_properties", {}
                        ) or {}).get("keyword_difficulty") or 0,
                    }
                )
    
            return sorted(keywords, key=lambda x: x["volume"], reverse=True)
    
        def _extract_content(self, raw: dict) -> Optional[dict]:
            """Extract content structure from on-page parsing.
    
            DataForSEO's content_parsing/live response shape (as of v0.1.20260420):
    
                tasks[0].result[0].items[0]
                  .page_content
                    .header           -- {primary_content, secondary_content}
                    .main_topic[]     -- each: {h_title, main_title, level, primary_content[]}
                    .secondary_topic[] -- each: {h_title, level, ...}
                    .footer
                  .page_as_markdown   -- full rendered markdown of the page
    
            There are no flat h1/h2/h3 arrays and no plain_text_word_count field.
            Headings come from main_topic + secondary_topic items keyed by `level`.
            Word count is computed from the markdown body.
            """
            tasks = raw.get("tasks", [])
            if not tasks:
                return None
    
            result = tasks[0].get("result", [])
            if not result:
                return None
    
            items = result[0].get("items") or []
            if not items:
                return None
    
            item = items[0]
            page = item.get("page_content", {}) or {}
            markdown = item.get("page_as_markdown", "") or ""
    
            return {
                "title": self._extract_title(page, markdown),
                "word_count": self._count_words(page, markdown),
                "headings": self._extract_headings(page),
                "plain_text_size": len(markdown),
                "links": self._extract_links(page),
            }
    
        @staticmethod
        def _extract_links(page_content: dict) -> list[dict]:
            """Extract anchor text + URL pairs from the content_parsing topic
            tree. DataForSEO stores links inside `primary_content[].urls[]`
            on both main_topic and secondary_topic items, with each url object
            carrying `url` and `anchor_text` fields. Used by missing_spokes
            extraction in research.py (v1.9.1)."""
            links: list[dict] = []
            for bucket in ("main_topic", "secondary_topic"):
                for topic in page_content.get(bucket) or []:
                    for entry in topic.get("primary_content") or []:
                        for u in (entry or {}).get("urls") or []:
                            anchor = ((u or {}).get("anchor_text") or "").strip()
                            url = ((u or {}).get("url") or "").strip()
                            if anchor and url:
                                links.append({"text": anchor, "url": url})
            return links
    
        @staticmethod
        def _extract_title(page_content: dict, markdown: str) -> str:
            """Best-effort title: first H1 in markdown, else first main_topic h_title."""
            # Try markdown H1 first (most reliable)
            for line in markdown.splitlines():
                if line.startswith("# ") and not line.startswith("## "):
                    return line[2:].strip()
            # Fallback: first main_topic h_title
            for topic in page_content.get("main_topic") or []:
                ht = topic.get("h_title")
                if ht:
                    return ht
            return ""
    
        @staticmethod
        def _count_words(page_content: dict, markdown: str) -> int:
            """Count words from rendered markdown (headings + body text)."""
            if markdown:
                # Strip markdown syntax noise then split on whitespace
                import re
                text = re.sub(r"[`*_#>\[\]()!|-]+", " ", markdown)
                return len([w for w in text.split() if w.strip()])
            # Fallback: walk topic primary_content text
            words = 0
            for bucket in ("main_topic", "secondary_topic"):
                for topic in page_content.get(bucket) or []:
                    for entry in topic.get("primary_content") or []:
                        text = (entry or {}).get("text") or ""
                        words += len(text.split())
            return words
    
        @staticmethod
        def _extract_headings(page_content: dict) -> list[str]:
            """Pull heading tags from parsed content.
    
            DataForSEO returns headings inside main_topic[] and secondary_topic[]
            as objects with `h_title` (text) and `level` (int 1-6, where 2 = H2).
            We surface them as 'H{level}: {text}' strings for the analyzer.
            """
            headings: list[str] = []
            for bucket in ("main_topic", "secondary_topic"):
                for topic in page_content.get(bucket) or []:
                    title = (topic.get("h_title") or "").strip()
                    if not title:
                        continue
                    level = topic.get("level")
                    if not isinstance(level, int) or level < 1 or level > 6:
                        level = 2  # safe default
                    headings.append(f"H{level}: {title}")
            return headings
    
  • scripts/lib/env.py4.6 KB2e9c41e81302upstream ↗
    """
    seo-agi environment and configuration loader.
    Reads API keys from ~/.config/seo-agi/.env or os.environ.
    Resolves paths relative to the skill installation directory.
    """
    
    import os
    import json
    from pathlib import Path
    
    # Skill root is two levels up from this file (scripts/lib/env.py -> .)
    SKILL_DIR = Path(__file__).resolve().parent.parent.parent
    
    OUTPUT_DIR = Path.home() / "Documents" / "SEO-AGI"
    DATA_DIR = Path.home() / ".local" / "share" / "seo-agi"
    CONFIG_DIR = Path.home() / ".config" / "seo-agi"
    ENV_FILE = CONFIG_DIR / ".env"
    
    DEFAULT_CONFIG = {
        "default_location": 2840,
        "default_language": "en",
        "default_site": "",
        "serp_depth": 10,
        "save_research": True,
        "output_dir": str(OUTPUT_DIR),
    }
    
    
    def load_env() -> dict:
        """
        Load environment variables.
        Reads from ~/.config/seo-agi/.env first, then overlays os.environ.
        """
        env = {}
    
        # First, try the config file
        if ENV_FILE.exists():
            with open(ENV_FILE, "r") as f:
                for line in f:
                    line = line.strip()
                    if not line or line.startswith("#"):
                        continue
                    if "=" in line:
                        key, _, value = line.partition("=")
                        key = key.strip()
                        value = value.strip().strip('"').strip("'")
                        if value:
                            env[key] = value
    
        # Then overlay with os.environ
        for key in [
            "DATAFORSEO_LOGIN", "DATAFORSEO_PASSWORD",
            "GSC_SERVICE_ACCOUNT_PATH", "GSC_CLIENT_ID",
            "GSC_CLIENT_SECRET", "GSC_REFRESH_TOKEN",
            "AHREFS_API_KEY", "SEMRUSH_API_KEY",
            "MASSIVE_API_TOKEN",
        ]:
            val = os.environ.get(key)
            if val:
                env[key] = val
    
        return env
    
    
    def load_config() -> dict:
        """Load user config, merged with defaults."""
        config = DEFAULT_CONFIG.copy()
        config_file = CONFIG_DIR / "config.json"
        if config_file.exists():
            try:
                with open(config_file, "r") as f:
                    user_config = json.load(f)
                config.update(user_config)
            except (json.JSONDecodeError, IOError):
                pass
        return config
    
    
    def get_credentials() -> dict:
        """Get API credentials with availability flags."""
        env = load_env()
    
        creds = {
            "dataforseo_login": env.get("DATAFORSEO_LOGIN", ""),
            "dataforseo_password": env.get("DATAFORSEO_PASSWORD", ""),
            "gsc_service_account_path": env.get("GSC_SERVICE_ACCOUNT_PATH", ""),
            "gsc_client_id": env.get("GSC_CLIENT_ID", ""),
            "gsc_client_secret": env.get("GSC_CLIENT_SECRET", ""),
            "gsc_refresh_token": env.get("GSC_REFRESH_TOKEN", ""),
            "ahrefs_api_key": env.get("AHREFS_API_KEY", ""),
            "semrush_api_key": env.get("SEMRUSH_API_KEY", ""),
            "massive_api_token": env.get("MASSIVE_API_TOKEN", ""),
        }
    
        creds["has_dataforseo"] = bool(
            creds["dataforseo_login"] and creds["dataforseo_password"]
        )
        creds["has_gsc"] = bool(
            creds["gsc_service_account_path"]
            or (creds["gsc_client_id"] and creds["gsc_client_secret"])
        )
        creds["has_ahrefs"] = bool(creds["ahrefs_api_key"])
        creds["has_semrush"] = bool(creds["semrush_api_key"])
        creds["has_massive"] = bool(creds["massive_api_token"])
    
        return creds
    
    
    def ensure_dirs():
        """Create output directories if they don't exist."""
        config = load_config()
        output_dir = Path(config["output_dir"]).expanduser()
    
        for subdir in ["research", "briefs", "pages", "rewrites"]:
            (output_dir / subdir).mkdir(parents=True, exist_ok=True)
    
        (DATA_DIR / "research").mkdir(parents=True, exist_ok=True)
        (DATA_DIR / "cache").mkdir(parents=True, exist_ok=True)
    
    
    def check_setup() -> dict:
        """Check setup status and return a summary."""
        creds = get_credentials()
        config = load_config()
    
        return {
            "runtime": "claude-code",
            "skill_dir": str(SKILL_DIR),
            "config_dir_exists": CONFIG_DIR.exists(),
            "env_file_exists": ENV_FILE.exists(),
            "has_dataforseo": creds["has_dataforseo"],
            "has_gsc": creds["has_gsc"],
            "has_ahrefs": creds["has_ahrefs"],
            "has_semrush": creds["has_semrush"],
            "default_location": config["default_location"],
            "default_language": config["default_language"],
            "mode": _determine_mode(creds),
        }
    
    
    def _determine_mode(creds: dict) -> str:
        """Determine operational mode based on available credentials."""
        if creds["has_dataforseo"] and creds["has_gsc"]:
            return "full"
        elif creds["has_dataforseo"]:
            return "dataforseo-only"
        elif creds["has_gsc"]:
            return "gsc-only"
        else:
            return "fallback"
    
  • scripts/lib/gsc_client.py5.4 KB9b6b330e1fdbupstream ↗
    """
    Google Search Console API client for SEO-AGI.
    Pulls query performance data, cannibalization detection, and indexing status.
    """
    
    import json
    from typing import Optional
    from pathlib import Path
    
    
    class GSCClient:
        """Client for Google Search Console API."""
    
        def __init__(self, credentials_path: str = None, oauth_creds: dict = None):
            """
            Initialize GSC client.
    
            Args:
                credentials_path: Path to service account JSON file
                oauth_creds: Dict with client_id, client_secret, refresh_token
            """
            self.credentials_path = credentials_path
            self.oauth_creds = oauth_creds
            self._service = None
    
        def _get_service(self):
            """Lazy-initialize the GSC API service."""
            if self._service is not None:
                return self._service
    
            try:
                from google.oauth2 import service_account
                from googleapiclient.discovery import build
            except ImportError:
                raise RuntimeError(
                    "GSC requires google-auth and google-api-python-client. "
                    "Install with: pip install google-auth google-api-python-client"
                )
    
            if self.credentials_path:
                creds = service_account.Credentials.from_service_account_file(
                    self.credentials_path,
                    scopes=["https://www.googleapis.com/auth/webmasters.readonly"],
                )
            else:
                raise RuntimeError(
                    "OAuth2 flow not yet implemented. Use a service account."
                )
    
            self._service = build("searchconsole", "v1", credentials=creds)
            return self._service
    
        def query_performance(
            self,
            site_url: str,
            keyword: str = None,
            days: int = 90,
            min_impressions: int = 10,
            row_limit: int = 100,
        ) -> list[dict]:
            """
            Pull query performance data from GSC.
    
            Args:
                site_url: The GSC property URL (e.g., "https://example.com")
                keyword: Optional keyword filter (partial match)
                days: Lookback period in days
                min_impressions: Minimum impressions threshold
                row_limit: Max rows to return
    
            Returns:
                List of dicts with query, page, clicks, impressions, ctr, position
            """
            from datetime import datetime, timedelta
    
            service = self._get_service()
    
            end_date = datetime.now().strftime("%Y-%m-%d")
            start_date = (datetime.now() - timedelta(days=days)).strftime("%Y-%m-%d")
    
            request_body = {
                "startDate": start_date,
                "endDate": end_date,
                "dimensions": ["query", "page"],
                "rowLimit": row_limit,
                "dimensionFilterGroups": [],
            }
    
            if keyword:
                request_body["dimensionFilterGroups"].append(
                    {
                        "filters": [
                            {
                                "dimension": "query",
                                "operator": "contains",
                                "expression": keyword,
                            }
                        ]
                    }
                )
    
            response = (
                service.searchanalytics()
                .query(siteUrl=site_url, body=request_body)
                .execute()
            )
    
            rows = response.get("rows", [])
            results = []
    
            for row in rows:
                impressions = row.get("impressions", 0)
                if impressions < min_impressions:
                    continue
    
                results.append(
                    {
                        "query": row["keys"][0],
                        "page": row["keys"][1],
                        "clicks": row.get("clicks", 0),
                        "impressions": impressions,
                        "ctr": round(row.get("ctr", 0) * 100, 2),
                        "position": round(row.get("position", 0), 1),
                    }
                )
    
            return sorted(results, key=lambda x: x["impressions"], reverse=True)
    
        def detect_cannibalization(
            self,
            site_url: str,
            keyword: str,
            days: int = 90,
        ) -> list[dict]:
            """
            Detect keyword cannibalization: multiple pages ranking for same query.
    
            Returns:
                List of queries where 2+ pages from the site appear,
                sorted by total impressions.
            """
            results = self.query_performance(
                site_url=site_url,
                keyword=keyword,
                days=days,
                min_impressions=5,
                row_limit=500,
            )
    
            # Group by query
            query_pages = {}
            for row in results:
                q = row["query"]
                if q not in query_pages:
                    query_pages[q] = []
                query_pages[q].append(row)
    
            # Find queries with multiple pages
            cannibalized = []
            for query, pages in query_pages.items():
                if len(pages) > 1:
                    cannibalized.append(
                        {
                            "query": query,
                            "page_count": len(pages),
                            "pages": sorted(
                                pages, key=lambda x: x["position"]
                            ),
                            "total_impressions": sum(
                                p["impressions"] for p in pages
                            ),
                        }
                    )
    
            return sorted(
                cannibalized,
                key=lambda x: x["total_impressions"],
                reverse=True,
            )
    
  • scripts/lib/massive.py4.8 KB36fc1199ef6fupstream ↗
    """
    Massive Web Render API client for seo-agi.
    
    Massive (render.joinmassive.com) is used for COMPETITOR CONTENT PARSING --
    fetching a URL and getting back clean rendered markdown that includes
    JS-loaded content, which DataForSEO's content_parsing/live endpoint misses.
    
    Scope intentionally narrow:
    - Massive /browser endpoint: URL -> markdown (used here)
    - Massive /search endpoint: NOT used. As of v1.9.0 it returns only
      'also-searched' query suggestions, not organic SERP results. SERP
      data continues to come from DataForSEO.
    
    The client outputs the same shape as DataForSEOClient._extract_content
    (`title`, `word_count`, `headings`, `plain_text_size`) so it is a
    drop-in replacement for the content_parse() step in research.py.
    """
    
    import json
    import re
    import urllib.parse
    import urllib.request
    import urllib.error
    from typing import Optional
    
    
    class MassiveClient:
        """Client for Massive Web Render API (render.joinmassive.com)."""
    
        BASE_URL = "https://render.joinmassive.com"
    
        def __init__(self, api_token: str, default_country: str = "US"):
            self.api_token = api_token
            self.default_country = default_country
    
        def _headers(self) -> dict:
            return {"Authorization": f"Bearer {self.api_token}"}
    
        def _get(self, path: str, params: dict, timeout: int = 60) -> str:
            """Make a GET request and return the raw response body as text."""
            qs = urllib.parse.urlencode(params)
            url = f"{self.BASE_URL}{path}?{qs}"
            req = urllib.request.Request(url, headers=self._headers())
            try:
                with urllib.request.urlopen(req, timeout=timeout) as resp:
                    return resp.read().decode("utf-8", errors="ignore")
            except urllib.error.HTTPError as e:
                body = e.read().decode("utf-8", errors="ignore") if e.fp else ""
                raise RuntimeError(
                    f"Massive API error {e.code}: {body[:300]}"
                ) from e
            except urllib.error.URLError as e:
                raise RuntimeError(f"Massive connection error: {e.reason}") from e
    
        def content_parse(
            self, url: str, country: Optional[str] = None
        ) -> Optional[dict]:
            """Fetch a URL via Massive's renderer and extract content structure.
    
            Returns the same shape as DataForSEOClient.content_parse():
                { "title": str, "word_count": int, "headings": [str],
                  "plain_text_size": int }
            where each heading is formatted as "H{level}: {text}".
    
            Returns None if the fetch returns empty content.
            """
            try:
                markdown = self._get(
                    "/browser",
                    {
                        "url": url,
                        "format": "markdown",
                        "country": country or self.default_country,
                    },
                )
            except RuntimeError:
                return None
    
            if not markdown or not markdown.strip():
                return None
    
            return self._parse_markdown(markdown)
    
        @staticmethod
        def _parse_markdown(md: str) -> dict:
            """Parse rendered markdown into the seo-agi content shape.
    
            Headings: lines starting with `#`, `##`, ..., `######` -> H1..H6.
            Title: first H1 found, otherwise empty.
            Word count: rough split of body text after stripping markdown
            syntax (consistent with how dataforseo.py counts).
            Links: markdown `[text](url)` extraction for spoke detection.
            """
            headings: list[str] = []
            title = ""
            for line in md.splitlines():
                m = re.match(r"^(#{1,6})\s+(.+?)\s*$", line)
                if not m:
                    continue
                level = len(m.group(1))
                text = m.group(2).strip()
                if not text:
                    continue
                if level == 1 and not title:
                    title = text
                headings.append(f"H{level}: {text}")
    
            # Word count: strip markdown punctuation, split on whitespace.
            text = re.sub(r"[`*_#>\[\]()!|-]+", " ", md)
            word_count = len([w for w in text.split() if w.strip()])
    
            # Links (v1.9.1): standard markdown [text](url). Skip image links
            # ![alt](src) -- those don't carry semantic anchor signal.
            links: list[dict] = []
            link_re = re.compile(r"(?<!!)\[([^\]]+)\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)")
            for m in link_re.finditer(md):
                anchor = m.group(1).strip()
                url = m.group(2).strip()
                if not anchor or not url:
                    continue
                # Skip pure-hash/javascript/empty anchors -- no spoke value
                if url.startswith(("#", "javascript:", "mailto:", "tel:")):
                    continue
                links.append({"text": anchor, "url": url})
    
            return {
                "title": title,
                "word_count": word_count,
                "headings": headings,
                "plain_text_size": len(md),
                "links": links,
            }
    
  • scripts/lib/serp_analyze.py6.9 KB2d2e00f34be9upstream ↗
    """
    SERP content analyzer for SEO-AGI.
    Analyzes competitor content structure and identifies content gaps.
    """
    
    import statistics
    from typing import Optional
    
    
    def analyze_serp(
        serp_data: dict,
        content_data: list[Optional[dict]],
        target_keyword: str,
    ) -> dict:
        """
        Analyze SERP results + parsed competitor content.
    
        Args:
            serp_data: Output from DataForSEOClient.serp_live()
            content_data: List of DataForSEOClient.content_parse() results
                (one per organic result, may contain None for failed parses)
            target_keyword: The keyword being targeted
    
        Returns:
            Analysis dict with intent, word count stats, topic coverage, gaps.
        """
        organic = serp_data.get("organic", [])
        paa = serp_data.get("paa", [])
    
        # Word count analysis
        word_counts = []
        all_headings = []
        all_topics = set()
    
        for i, content in enumerate(content_data):
            if content is None:
                continue
    
            wc = content.get("word_count", 0)
            if wc > 0:
                word_counts.append(wc)
    
            headings = content.get("headings", [])
            all_headings.extend(headings)
    
            # Extract topics from H2/H3 headings
            for h in headings:
                if h.startswith(("H2:", "H3:")):
                    topic = h.split(":", 1)[1].strip().lower()
                    all_topics.add(topic)
    
        # Word count statistics
        wc_stats = {}
        if word_counts:
            wc_stats = {
                "min": min(word_counts),
                "max": max(word_counts),
                "median": int(statistics.median(word_counts)),
                "mean": int(statistics.mean(word_counts)),
                "recommended_min": int(statistics.median(word_counts) * 0.8),
                "recommended_max": int(statistics.median(word_counts) * 1.3),
                "count_analyzed": len(word_counts),
            }
    
        # Intent detection
        intent = detect_intent(target_keyword, organic, serp_data)
    
        # Topic frequency (which topics appear in multiple competitors)
        topic_freq = _count_topic_frequency(content_data)
    
        # Heading patterns
        heading_patterns = _analyze_heading_patterns(content_data)
    
        return {
            "keyword": target_keyword,
            "intent": intent,
            "word_count_stats": wc_stats,
            "paa_questions": paa,
            "topic_frequency": topic_freq,
            "heading_patterns": heading_patterns,
            "competitors_analyzed": len(
                [c for c in content_data if c is not None]
            ),
            "total_organic_results": len(organic),
            "featured_snippet": serp_data.get("featured_snippet"),
        }
    
    
    def detect_intent(
        keyword: str, organic: list[dict], serp_data: dict
    ) -> str:
        """
        Detect search intent from keyword and SERP features.
    
        Returns: informational, commercial, transactional, or navigational
        """
        kw_lower = keyword.lower()
    
        # Navigational signals
        nav_signals = [
            "login",
            "sign in",
            "website",
            "official",
            ".com",
            ".org",
        ]
        if any(s in kw_lower for s in nav_signals):
            return "navigational"
    
        # Transactional signals
        transactional_signals = [
            "buy",
            "purchase",
            "order",
            "download",
            "subscribe",
            "deal",
            "discount",
            "coupon",
            "price",
            "pricing",
            "cost",
            "cheap",
            "free trial",
        ]
        if any(s in kw_lower for s in transactional_signals):
            return "transactional"
    
        # Commercial investigation signals
        commercial_signals = [
            "best",
            "top",
            "review",
            "comparison",
            "vs",
            "versus",
            "alternative",
            "vs.",
            "compared to",
            "pros and cons",
        ]
        if any(s in kw_lower for s in commercial_signals):
            return "commercial"
    
        # Informational signals
        informational_signals = [
            "how to",
            "what is",
            "what are",
            "why",
            "guide",
            "tutorial",
            "learn",
            "example",
            "definition",
            "meaning",
            "explain",
        ]
        if any(s in kw_lower for s in informational_signals):
            return "informational"
    
        # Default: check SERP patterns
        if serp_data.get("featured_snippet"):
            return "informational"
    
        # If titles contain pricing/comparison language
        titles = [r.get("title", "").lower() for r in organic[:5]]
        title_text = " ".join(titles)
    
        if any(s in title_text for s in ["best", "top", "review", "vs"]):
            return "commercial"
        if any(
            s in title_text for s in ["how to", "guide", "what", "tutorial"]
        ):
            return "informational"
    
        return "commercial"  # default for ambiguous
    
    
    def _count_topic_frequency(
        content_data: list[Optional[dict]],
    ) -> list[dict]:
        """Count how often topics (H2/H3 headings) appear across competitors."""
        topic_counts = {}
    
        for content in content_data:
            if content is None:
                continue
    
            seen_in_page = set()
            for heading in content.get("headings", []):
                if heading.startswith(("H2:", "H3:")):
                    topic = heading.split(":", 1)[1].strip().lower()
                    # Normalize common variations
                    topic = _normalize_topic(topic)
                    if topic and topic not in seen_in_page:
                        seen_in_page.add(topic)
                        topic_counts[topic] = topic_counts.get(topic, 0) + 1
    
        # Sort by frequency
        sorted_topics = sorted(
            topic_counts.items(), key=lambda x: x[1], reverse=True
        )
        return [
            {"topic": t, "competitor_count": c} for t, c in sorted_topics[:30]
        ]
    
    
    def _normalize_topic(topic: str) -> str:
        """Basic topic normalization."""
        # Remove common filler words at start
        for prefix in [
            "the ",
            "a ",
            "an ",
            "our ",
            "your ",
            "my ",
            "about ",
        ]:
            if topic.startswith(prefix):
                topic = topic[len(prefix) :]
    
        # Strip trailing punctuation
        topic = topic.rstrip(".:!?")
    
        return topic.strip()
    
    
    def _analyze_heading_patterns(
        content_data: list[Optional[dict]],
    ) -> dict:
        """Analyze heading patterns across competitors."""
        h2_counts = []
        h3_counts = []
    
        for content in content_data:
            if content is None:
                continue
    
            headings = content.get("headings", [])
            h2_count = sum(1 for h in headings if h.startswith("H2:"))
            h3_count = sum(1 for h in headings if h.startswith("H3:"))
            h2_counts.append(h2_count)
            h3_counts.append(h3_count)
    
        return {
            "avg_h2_count": (
                round(statistics.mean(h2_counts), 1) if h2_counts else 0
            ),
            "avg_h3_count": (
                round(statistics.mean(h3_counts), 1) if h3_counts else 0
            ),
            "median_h2_count": (
                int(statistics.median(h2_counts)) if h2_counts else 0
            ),
            "median_h3_count": (
                int(statistics.median(h3_counts)) if h3_counts else 0
            ),
        }
    
  • scripts/research.py38 KBd3e4030c7b7cupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • scripts/setup.py5.3 KB47c86345079dupstream ↗
    #!/usr/bin/env python3
    """
    SEO-AGI setup script.
    Creates config directory, prompts for API keys, installs dependencies.
    
    Usage:
        python3 setup.py
    """
    
    import os
    import sys
    import json
    import subprocess
    from pathlib import Path
    
    CONFIG_DIR = Path.home() / ".config" / "seo-agi"
    ENV_FILE = CONFIG_DIR / ".env"
    CONFIG_FILE = CONFIG_DIR / "config.json"
    OUTPUT_DIR = Path.home() / "Documents" / "SEO-AGI"
    
    
    def main():
        print("=" * 50)
        print("  SEO-AGI Setup")
        print("=" * 50)
        print()
    
        # Create directories
        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
        for subdir in ["research", "briefs", "pages", "rewrites"]:
            (OUTPUT_DIR / subdir).mkdir(parents=True, exist_ok=True)
    
        data_dir = Path.home() / ".local" / "share" / "seo-agi"
        for subdir in ["research", "cache"]:
            (data_dir / subdir).mkdir(parents=True, exist_ok=True)
    
        print("[OK] Directories created")
    
        # Install Python dependencies
        print("\nInstalling dependencies...")
        deps = ["requests"]
        try:
            subprocess.check_call(
                [sys.executable, "-m", "pip", "install", "--quiet"]
                + deps
                + ["--break-system-packages"],
                stdout=subprocess.DEVNULL,
                stderr=subprocess.DEVNULL,
            )
            print("[OK] Core dependencies installed (requests)")
        except subprocess.CalledProcessError:
            try:
                subprocess.check_call(
                    [sys.executable, "-m", "pip", "install", "--quiet"] + deps,
                    stdout=subprocess.DEVNULL,
                    stderr=subprocess.DEVNULL,
                )
                print("[OK] Core dependencies installed (requests)")
            except subprocess.CalledProcessError:
                print("[WARN] Could not install requests. Install manually:")
                print("       pip install requests")
    
        # API Keys
        print("\n--- API Keys ---")
        print("DataForSEO is REQUIRED. Get credentials at:")
        print("  https://app.dataforseo.com/api-dashboard\n")
    
        existing_env = {}
        if ENV_FILE.exists():
            with open(ENV_FILE) as f:
                for line in f:
                    line = line.strip()
                    if line and not line.startswith("#") and "=" in line:
                        k, _, v = line.partition("=")
                        existing_env[k.strip()] = v.strip()
    
        # DataForSEO
        dfs_login = existing_env.get("DATAFORSEO_LOGIN", "")
        dfs_pass = existing_env.get("DATAFORSEO_PASSWORD", "")
    
        if dfs_login:
            print(f"DataForSEO login found: {dfs_login[:4]}***")
            change = input("Update DataForSEO credentials? [y/N]: ").strip().lower()
            if change == "y":
                dfs_login = input("DataForSEO login (email): ").strip()
                dfs_pass = input("DataForSEO password: ").strip()
        else:
            dfs_login = input("DataForSEO login (email): ").strip()
            dfs_pass = input("DataForSEO password: ").strip()
    
        # GSC (optional)
        print("\nGoogle Search Console (OPTIONAL - press Enter to skip)")
        gsc_path = existing_env.get("GSC_SERVICE_ACCOUNT_PATH", "")
        if gsc_path:
            print(f"GSC service account found: {gsc_path}")
            change = input("Update? [y/N]: ").strip().lower()
            if change == "y":
                gsc_path = input("Path to service account JSON: ").strip()
        else:
            gsc_path = input("Path to GSC service account JSON (or Enter to skip): ").strip()
    
        # Write .env
        env_lines = [
            "# SEO-AGI Configuration",
            f"# Generated by setup.py on {__import__('datetime').datetime.now().isoformat()[:10]}",
            "",
            "# DataForSEO",
            f"DATAFORSEO_LOGIN={dfs_login}",
            f"DATAFORSEO_PASSWORD={dfs_pass}",
            "",
            "# Google Search Console",
            f"GSC_SERVICE_ACCOUNT_PATH={gsc_path}",
            "",
            "# Future integrations",
            f"AHREFS_API_KEY={existing_env.get('AHREFS_API_KEY', '')}",
            f"SEMRUSH_API_KEY={existing_env.get('SEMRUSH_API_KEY', '')}",
            "",
            "# Defaults",
            f"DEFAULT_LOCATION={existing_env.get('DEFAULT_LOCATION', '2840')}",
            f"DEFAULT_LANGUAGE={existing_env.get('DEFAULT_LANGUAGE', 'en')}",
        ]
    
        with open(ENV_FILE, "w") as f:
            f.write("\n".join(env_lines) + "\n")
    
        print(f"\n[OK] Credentials saved to {ENV_FILE}")
    
        # Write default config.json if not exists
        if not CONFIG_FILE.exists():
            default_config = {
                "default_location": 2840,
                "default_language": "en",
                "default_site": "",
                "serp_depth": 10,
                "save_research": True,
                "output_dir": str(OUTPUT_DIR),
            }
            with open(CONFIG_FILE, "w") as f:
                json.dump(default_config, f, indent=2)
            print(f"[OK] Config saved to {CONFIG_FILE}")
    
        # Verify
        print("\n--- Setup Summary ---")
        print(f"  DataForSEO: {'configured' if dfs_login else 'NOT SET'}")
        print(f"  GSC:         {'configured' if gsc_path else 'not configured (optional)'}")
        print(f"  Output dir:  {OUTPUT_DIR}")
        print(f"  Config dir:  {CONFIG_DIR}")
    
        if dfs_login:
            print("\n[READY] Run a test:")
            print(f"  python3 {Path(__file__).parent}/research.py \"test keyword\"")
        else:
            print("\n[WARN] DataForSEO credentials missing. The skill will fall")
            print("       back to Claude's web search for basic research.")
    
        print()
    
    
    if __name__ == "__main__":
        main()
    
  • scripts/tributary_gen.py12 KBb3d09bae58ffupstream ↗
    #!/usr/bin/env python3
    """
    tributary_gen.py -- Generate Tier 1/Tier 2 companion content briefs
    for the Tributary Trust Protocol (see SKILL.md, Section 11A).
    
    This script does NOT write final tributary content. It:
      1. Reads the money page (markdown file or URL)
      2. Extracts its 500-token chunks, key entities, target keyword, and
         verification tags
      3. Derives one companion brief per Tier 1 asset, mapped to the chunk
         each tributary covers in greater depth
      4. Writes structured drafts to ~/Documents/SEO-AGI/tributaries/<slug>/
         plus a manifest.json mapping each draft to its host platform
    
    The agent then refines each draft into platform-native voice and applies
    all SKILL.md quality gates (Reddit Test, Information Gain, {{VERIFY}}
    resolution, Section 9 banned patterns) before publishing.
    
    Usage:
      python3 tributary_gen.py "<keyword>" --money-page=<path-or-url> [--tiers=1]
      python3 tributary_gen.py "airport parking JFK" --money-page=~/Documents/SEO-AGI/pages/jfk.md
      python3 tributary_gen.py "best crm 2026" --money-page=https://example.com/best-crm
    """
    
    import argparse
    import json
    import re
    import sys
    import urllib.request
    from datetime import datetime, timezone
    from pathlib import Path
    
    OUTPUT_ROOT = Path.home() / "Documents" / "SEO-AGI" / "tributaries"
    
    TIER_1_ASSETS = [
        {
            "host": "google_sites",
            "label": "Google Sites",
            "voice": "encyclopedic, structured, neutral; uses headings, embedded maps where geo-relevant, simple tables",
            "derives_from": "geographic/local detail OR pricing comparison table",
            "min_words": 600,
            "anchor_text_pattern": "entity-rich descriptive (e.g., 'JFK long-term parking rates')",
        },
        {
            "host": "medium",
            "label": "Medium",
            "voice": "essay/narrative, first-person observation, expanded operational detail, photos if available",
            "derives_from": "Original Research / Data Experiment block",
            "min_words": 1000,
            "anchor_text_pattern": "in-line natural mentions plus one bottom-of-article reference",
        },
        {
            "host": "subreddit",
            "label": "Custom Subreddit (you moderate)",
            "voice": "community thread, Q&A reframed, mod-pinned canonical answer",
            "derives_from": "FAQ / PAA section",
            "min_words": 400,
            "anchor_text_pattern": "single contextual link in mod-pinned comment",
        },
        {
            "host": "google_sheets",
            "label": "Google Sheets (published to web)",
            "voice": "tabular, methodology notes in cell comments, formula transparency",
            "derives_from": "pricing comparison table OR break-even math",
            "min_words": 200,
            "anchor_text_pattern": "header cell linking back to money page methodology section",
        },
        {
            "host": "linkedin",
            "label": "LinkedIn Article",
            "voice": "industry-framed, methodology deep-dive, peer commentary invitation",
            "derives_from": "Original Research block OR Information Gain insight",
            "min_words": 800,
            "anchor_text_pattern": "in-line entity mention plus 'further reading' reference",
        },
    ]
    
    TIER_2_ASSETS = [
        {
            "host": "youtube_description",
            "label": "YouTube video description + transcript",
            "voice": "spoken-style transcript, timestamped sections",
            "derives_from": "any 500-token chunk with visual potential",
            "min_words": 300,
            "anchor_text_pattern": "first-line link in description",
        },
        {
            "host": "github_readme",
            "label": "GitHub repository README",
            "voice": "technical, code-friendly, citation-heavy",
            "derives_from": "data/methodology if vertical is technical",
            "min_words": 500,
            "anchor_text_pattern": "Resources section link",
        },
        {
            "host": "substack",
            "label": "Substack newsletter post",
            "voice": "newsletter conversational, weekly framing",
            "derives_from": "any chunk reframed as 'this week's analysis'",
            "min_words": 600,
            "anchor_text_pattern": "in-line plus footer 'further reading'",
        },
    ]
    
    
    def slugify(text: str) -> str:
        s = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
        return s[:60] or "untitled"
    
    
    def load_money_page(source: str) -> str:
        """Load money page from local path or URL. Returns raw markdown/HTML."""
        src = source.strip()
        if src.startswith(("http://", "https://")):
            req = urllib.request.Request(
                src, headers={"User-Agent": "seobuild-onpage/1.7.0"}
            )
            with urllib.request.urlopen(req, timeout=30) as resp:
                return resp.read().decode("utf-8", errors="ignore")
        path = Path(src).expanduser()
        if not path.exists():
            raise FileNotFoundError(f"Money page not found: {path}")
        return path.read_text(encoding="utf-8")
    
    
    def extract_chunks(content: str) -> list[dict]:
        """Naive 500-token chunk extraction by H2 boundary.
    
        A chunk is the H2 heading and the body text that follows up to the
        next H2. Each chunk is a distinct QFO facet candidate per
        SKILL.md Section 3.
        """
        # Strip YAML frontmatter
        if content.startswith("---"):
            end = content.find("\n---", 3)
            if end != -1:
                content = content[end + 4 :]
    
        chunks = []
        current = {"h2": None, "body": []}
        for line in content.splitlines():
            if line.startswith("## ") and not line.startswith("### "):
                if current["h2"] or current["body"]:
                    chunks.append(current)
                current = {"h2": line[3:].strip(), "body": []}
            else:
                current["body"].append(line)
        if current["h2"] or current["body"]:
            chunks.append(current)
    
        # Filter empty / no-h2 prelude
        return [
            {
                "h2": c["h2"],
                "body": "\n".join(c["body"]).strip(),
                "word_count": len(" ".join(c["body"]).split()),
            }
            for c in chunks
            if c["h2"]
        ]
    
    
    def extract_entities(content: str) -> list[str]:
        """Best-effort entity extraction. Looks for proper-noun phrases and
        inline RDFa span markers (`<span typeof="...">`). Real entity work
        happens in the agent layer; this is a starting list."""
        entities = set()
        # RDFa spans
        for m in re.finditer(r'<span[^>]*typeof="[^"]+"[^>]*>([^<]+)</span>', content):
            entities.add(m.group(1).strip())
        # Capitalized multi-word phrases (rough heuristic)
        for m in re.finditer(r"\b([A-Z][A-Za-z]+(?:\s+[A-Z][A-Za-z]+){1,4})\b", content):
            if len(m.group(1)) > 4:
                entities.add(m.group(1))
        return sorted(entities)[:30]
    
    
    def extract_verify_tags(content: str) -> list[str]:
        return re.findall(r"\{\{(?:VERIFY|RESEARCH NEEDED|SOURCE NEEDED)[^}]*\}\}", content)
    
    
    def derive_brief(asset: dict, keyword: str, chunks: list[dict], entities: list[str], verify_tags: list[str], money_page_ref: str) -> dict:
        """Build a tributary brief for one Tier 1 / Tier 2 asset."""
        # Pick a chunk to derive from. Heuristic: keyword match in h2 / body
        target_chunk = chunks[0] if chunks else {"h2": "(no chunks parsed)", "body": ""}
        for c in chunks:
            if asset["derives_from"].split()[0].lower() in (c["h2"] or "").lower():
                target_chunk = c
                break
    
        return {
            "host": asset["host"],
            "label": asset["label"],
            "target_keyword": keyword,
            "money_page": money_page_ref,
            "derives_from_chunk": target_chunk["h2"],
            "derives_from_facet": asset["derives_from"],
            "voice_directive": asset["voice"],
            "min_words": asset["min_words"],
            "anchor_text_pattern": asset["anchor_text_pattern"],
            "entities_to_mention": entities[:10],
            "inherited_verify_tags": verify_tags,
            "quality_gates_required": [
                "Reddit Test (host-platform appropriate)",
                "Information Gain Test (1+ fact not in top 10 SERP)",
                "Prove-It Details (2+ hard operational facts)",
                "All {{VERIFY}} / {{SOURCE NEEDED}} resolved before publish",
                "Section 9 banned patterns (no em dashes, no nestled, no generic intros)",
                "Entity Consensus (claims cross-checked against 2+ sources)",
                "Link to money page with descriptive anchor",
                "Cross-link to at least one other tributary in the network",
            ],
            "agent_instructions": (
                f"Refine this brief into a publish-ready {asset['label']} post. "
                f"Voice: {asset['voice']}. Cover the '{target_chunk['h2']}' "
                f"facet in greater depth than the money page does. Reuse the "
                f"entity names and key numbers verbatim for Entity Consensus. "
                f"Resolve every {{VERIFY}} tag with a real source before output."
            ),
        }
    
    
    def write_drafts(slug: str, briefs: list[dict], keyword: str, money_page_ref: str) -> Path:
        out_dir = OUTPUT_ROOT / slug
        out_dir.mkdir(parents=True, exist_ok=True)
    
        manifest = {
            "keyword": keyword,
            "money_page": money_page_ref,
            "generated": datetime.now(timezone.utc).isoformat(),
            "tributaries": [],
        }
    
        for brief in briefs:
            fname = f"{brief['host']}.md"
            path = out_dir / fname
            body = (
                f"# Tributary Brief: {brief['label']}\n\n"
                f"**Target keyword:** {brief['target_keyword']}\n"
                f"**Money page:** {brief['money_page']}\n"
                f"**Derives from chunk:** {brief['derives_from_chunk']}\n"
                f"**Facet:** {brief['derives_from_facet']}\n"
                f"**Min words:** {brief['min_words']}\n\n"
                f"## Voice\n{brief['voice_directive']}\n\n"
                f"## Anchor text pattern\n{brief['anchor_text_pattern']}\n\n"
                f"## Entities to mention (Entity Consensus)\n"
                + "".join(f"- {e}\n" for e in brief["entities_to_mention"])
                + "\n## Inherited {{VERIFY}} tags (must be resolved before publish)\n"
                + ("".join(f"- {t}\n" for t in brief["inherited_verify_tags"]) or "- (none)\n")
                + "\n## Quality gates (all required)\n"
                + "".join(f"- {g}\n" for g in brief["quality_gates_required"])
                + f"\n## Agent instructions\n{brief['agent_instructions']}\n\n"
                "---\n\n## Draft\n\n_Agent fills this section. Apply every "
                "quality gate above. Do not publish until all {{VERIFY}} tags "
                "are resolved._\n"
            )
            path.write_text(body, encoding="utf-8")
            manifest["tributaries"].append(
                {"host": brief["host"], "path": str(path), "min_words": brief["min_words"]}
            )
    
        (out_dir / "manifest.json").write_text(
            json.dumps(manifest, indent=2), encoding="utf-8"
        )
        return out_dir
    
    
    def main():
        p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
        p.add_argument("keyword", help="Target keyword for the money page")
        p.add_argument("--money-page", required=True, help="Path or URL to the money page")
        p.add_argument(
            "--tiers",
            default="1",
            help="Comma-separated tier numbers to generate (1 = Tier 1 only, '1,2' = both). Default: 1",
        )
        p.add_argument("--output-root", default=str(OUTPUT_ROOT), help="Override output dir")
        args = p.parse_args()
    
        try:
            content = load_money_page(args.money_page)
        except Exception as e:
            print(f"ERROR loading money page: {e}", file=sys.stderr)
            return 1
    
        chunks = extract_chunks(content)
        entities = extract_entities(content)
        verify_tags = extract_verify_tags(content)
    
        if not chunks:
            print(
                "WARNING: no H2 chunks parsed from money page. Tributary briefs "
                "will derive from generic facet hints instead of real chunks.",
                file=sys.stderr,
            )
    
        tier_set = {t.strip() for t in args.tiers.split(",")}
        assets = []
        if "1" in tier_set:
            assets.extend(TIER_1_ASSETS)
        if "2" in tier_set:
            assets.extend(TIER_2_ASSETS)
    
        briefs = [
            derive_brief(a, args.keyword, chunks, entities, verify_tags, args.money_page)
            for a in assets
        ]
    
        slug = slugify(args.keyword)
        out_dir = write_drafts(slug, briefs, args.keyword, args.money_page)
    
        print(f"Generated {len(briefs)} tributary brief(s) for: {args.keyword}")
        print(f"Output: {out_dir}")
        print(f"Manifest: {out_dir / 'manifest.json'}")
        print()
        print("Next: agent refines each draft to platform-native voice, applies")
        print("all quality gates, and resolves {{VERIFY}} tags before publish.")
        print("See SKILL.md Section 11A 'Tributary Trust Protocol' for full rules.")
        return 0
    
    
    if __name__ == "__main__":
        sys.exit(main())
    
  • references/page-templates.md7.6 KB9e1f0cec9ee6upstream ↗
    # Page Templates Reference
    
    Each page type has a specific structure that performs well in search.
    The skill auto-detects page type from the keyword intent, but users can override.
    
    ## Service Page
    
    **Triggers:** "[service] in [location]", "[service] company", "[service] near me"
    
    **Structure:**
    ```
    H1: [Service] in [Location] - [Value Prop]
      H2: What Is [Service] / How [Service] Works
      H2: [Service] Options / Types of [Service]
        H3: [Option 1]
        H3: [Option 2]
        H3: [Option 3]
      H2: Pricing / What Does [Service] Cost
      H2: How to Choose [a/the right] [Service Provider]
      H2: Why [Company/Location] for [Service]
      H2: Frequently Asked Questions
        H3: [PAA Question 1]
        H3: [PAA Question 2]
        H3: [PAA Question 3]
    ```
    
    **Schema:** LocalBusiness + FAQPage
    **Word count target:** 1500-2500
    **Must include:** Pricing (even ranges), specific location references, social proof
    
    ## Comparison Page
    
    **Triggers:** "[X] vs [Y]", "best [category]", "[product] alternatives", "top [N] [category]"
    
    **Structure:**
    ```
    H1: [X] vs [Y]: [Differentiating Angle] ([Year])
      H2: Quick Comparison / TL;DR
        [Comparison table]
      H2: What Is [X]
        H3: Key Features
        H3: Pricing
        H3: Best For
      H2: What Is [Y]
        H3: Key Features
        H3: Pricing
        H3: Best For
      H2: [X] vs [Y]: [Criteria 1]
      H2: [X] vs [Y]: [Criteria 2]
      H2: [X] vs [Y]: [Criteria 3]
      H2: Which Should You Choose?
      H2: FAQ
    ```
    
    **Schema:** FAQPage (+ Product if applicable)
    **Word count target:** 2000-3500
    **Must include:** Comparison table near top, specific criteria-based sections, clear recommendation
    
    ## How-To / Guide
    
    **Triggers:** "how to [action]", "[topic] guide", "[topic] tutorial"
    
    **Structure:**
    ```
    H1: How to [Action]: [Qualifier] Guide ([Year])
      H2: What You'll Need / Prerequisites
      H2: Step 1: [Action]
        H3: [Sub-step if complex]
      H2: Step 2: [Action]
      H2: Step 3: [Action]
      H2: [N] more steps...
      H2: Common Mistakes / Troubleshooting
      H2: Tips from [Experts/Experience]
      H2: FAQ
    ```
    
    **Schema:** HowTo + FAQPage
    **Word count target:** 1500-3000
    **Must include:** Numbered steps, specific examples, troubleshooting section
    
    ## Location Page
    
    **Triggers:** "[service] [city]", "[business type] [neighborhood]", "[thing to do] in [location]"
    
    **Structure:**
    ```
    H1: [Service/Topic] in [City, State] - [Value Prop]
      H2: [Service] Options in [City]
        H3: [Option/Area 1]
        H3: [Option/Area 2]
      H2: [City]-Specific Information
        [Local details: regulations, seasonality, landmarks, neighborhoods]
      H2: Pricing in [City]
      H2: How to [Get Started/Book/Find] [Service] in [City]
      H2: Tips for [Service] in [City]
      H2: Nearby Alternatives
        [Adjacent cities/neighborhoods]
      H2: FAQ
    ```
    
    **Schema:** LocalBusiness + FAQPage + BreadcrumbList
    **Word count target:** 1200-2000
    **Must include:** Specific local details (not generic), nearby alternatives for internal linking, local pricing
    
    ## Product / Feature Page
    
    **Triggers:** "[product] features", "[product] review", "[product] pricing"
    
    **Structure:**
    ```
    H1: [Product Name]: [Key Benefit] ([Year])
      H2: What Is [Product]
      H2: Key Features
        H3: [Feature 1] - [Benefit]
        H3: [Feature 2] - [Benefit]
        H3: [Feature 3] - [Benefit]
      H2: Pricing
        [Plans table or breakdown]
      H2: Pros and Cons
      H2: Who Is [Product] Best For
      H2: [Product] vs Alternatives
      H2: How to Get Started
      H2: FAQ
    ```
    
    **Schema:** Product + FAQPage + Review (if review angle)
    **Word count target:** 1500-2500
    **Must include:** Pricing specifics, honest pros/cons, clear "best for" segment
    
    ## General Quality Rules (All Templates)
    
    1. Every H2 section should have at least 150 words of substantive content
    2. FAQ sections use the exact PAA questions (or close variants) as H3s
    3. Include at least one data point, stat, or specific example per major section
    4. Internal links should go in contextually relevant spots, not dumped at the bottom
    5. Schema markup matches the page type (see schema-patterns.md)
    6. Year in title only if the content is genuinely time-sensitive
    7. No filler paragraphs. If a section doesn't add value, cut it.
    
    ---
    
    ## Universal Block Requirements (all templates, current as of v2.5.0)
    
    These apply on top of the per-type skeletons above. Where this section and an
    older rule above disagree, this section wins.
    
    ### Required blocks, in order
    
    1. **AI Summary Nugget** -- 200 characters maximum, first element after
       frontmatter, above the H1. Pure facts: primary entity, key number, core
       distinction. No marketing language. This is the passage answer engines lift
       as a consensus snippet.
    2. **Opening answer block** -- 100 to 150 words, third-person and objective.
       Answers the query directly, no preamble or definitional throat-clearing.
    3. **Fast-scan summary** -- within the first 200 words. Bullets with concrete
       facts, a key-takeaways box, or a comparison table.
    4. **Main body** -- 500-token chunks (see below).
    5. **Comparison table** -- real `<table>`, columns that do work: Best For,
       Main Tradeoff, Why It Matters, Typical Cost.
    6. **Prove-It section** -- two or more hard operational facts with traceable
       citations.
    7. **Original Research / Data Experiment block** -- a specific test, analysis,
       or first-hand observation. Pages without one cap out on the scorecard.
    8. **Not For You block** -- honest scenarios where this is the wrong choice.
       At least one line a competitor would never publish.
    9. **FAQ** -- three or more real PAA questions, wrapped in FAQPage schema.
    10. **Recommended Spoke Pages** -- built from `research.missing_spokes`,
        derived per page. Never the same list across pages.
    
    ### 500-token chunk architecture
    
    Each chunk is roughly 375 words and must stand alone as the answer to one
    specific sub-query (one QFO facet per chunk, never two). Within every chunk:
    
    - **Question-based H2** using entity names, never the exact-match keyword.
    - **Snippet answer** in the first 2-3 sentences, wrapped in a block-level
      structural container, not a bare `<p>`.
    - **Entity-fact pairing** -- every entity bound to a hard fact in that same
      chunk: time, place, cost, capacity, frequency, distance, or date.
    - **Named source attribution** -- major claims name their source in the visible
      copy, then link to it.
    - **Proof-term proximity** -- supporting evidence lives in the same chunk as the
      heading it supports.
    - Never split a table across a chunk boundary. Never stack two H2s without
      250+ words between them.
    
    ### Informational vs Local template separation
    
    The same page skeleton diverges by intent. Applying the wrong column demotes
    the page.
    
    | | Informational / global | Local service (Ask Maps) |
    |---|---|---|
    | Sales CTAs | Strip | Keep, maximum two |
    | "Free estimate" offers | Strip | Permitted |
    | Awards, badges, certifications | Strip from text layer, SVG only | Feature prominently |
    | Quantifiable differentiators | Omit | Required, two or more, hard numbers |
    | Outbound citations | 5+ required | 5+ required |
    | Service scope | Single topic cluster | Exactly one service, one location |
    | GBP directive | Not applicable | Required at top of brief |
    
    Determine intent from `research.primary_intent` before choosing a column.
    
    ### Hard limits
    
    - Exact-match keyword appears in the Title and H1 only. Never in H2/H3/H4,
      meta description, or alt text.
    - Five or more descriptive outbound links to external authoritative sources.
    - Maximum DOM nesting depth of roughly three levels in the content region.
    - Server-rendered or static output. Internal links must exist in the raw HTML.
    - No fabricated testing claims ("We tested 12 of these") unless the testing
      happened and the methodology is documented.
    - No skyscraper pages. Word count comes from the competitive median.
    - Internal links are contextual per chunk, never a repeated sitewide block.
    
  • references/quality-checklist.md20 KB10b09e690f30upstream ↗
    # Content Quality Checklist
    
    SEO-AGI validates every page against this checklist before final output.
    Each item is scored pass/fail. Pages scoring below 80% get flagged with
    specific items to fix.
    
    ## Title Tag (10 points)
    
    - [ ] Contains target keyword (or close variant)
    - [ ] Under 60 characters
    - [ ] Unique and compelling (not just "[Keyword] | [Brand]")
    - [ ] Includes a differentiating element (year, number, qualifier)
    - [ ] Not duplicating another page's title on the same site
    
    ## Meta Description (10 points)
    
    - [ ] Under 155 characters
    - [ ] Contains target keyword naturally
    - [ ] Includes a call-to-action or value proposition
    - [ ] Not a copy of the first paragraph
    - [ ] Would make someone click vs competitors in the SERP
    
    ## Heading Structure (15 points)
    
    - [ ] Exactly one H1
    - [ ] H1 closely matches or mirrors title tag
    - [ ] Logical H2 > H3 hierarchy (no skipped levels)
    - [ ] H2 count within competitive range (see analysis)
    - [ ] Headings are descriptive (not "Section 1" or "More Info")
    
    ## Content Depth (25 points)
    
    - [ ] Word count within competitive range (not arbitrarily long or short)
    - [ ] Answers at least 3 People Also Ask questions
    - [ ] Includes specific data, statistics, or concrete examples
    - [ ] Covers topics that appear in 2+ competitor pages
    - [ ] No thin sections (every H2 has 150+ words of substance)
    
    ## Search Intent Match (15 points)
    
    - [ ] Page type matches detected intent (informational/commercial/transactional)
    - [ ] Content format matches SERP expectations (list vs guide vs comparison)
    - [ ] Addresses the primary user need within the first 200 words
    - [ ] If commercial intent: includes pricing or comparison elements
    - [ ] If informational intent: includes step-by-step or explanatory depth
    
    ## Technical SEO (15 points)
    
    - [ ] JSON-LD schema markup included and matches page type
    - [ ] Schema uses correct types (see schema-patterns.md)
    - [ ] Image alt text suggestions included
    - [ ] At least 2 internal link suggestions with context
    - [ ] No orphaned sections (every section connects to the page's topic)
    
    ## Readability (10 points)
    
    - [ ] No keyword stuffing (target keyword appears naturally, not forced)
    - [ ] Paragraphs are scannable (no walls of text)
    - [ ] Uses formatting aids where appropriate (bold key terms, tables for comparisons)
    - [ ] Transitions between sections are logical
    - [ ] Reads like it was written by a subject matter expert, not a content mill
    
    ## Scoring
    
    | Score | Rating | Action |
    |---|---|---|
    | 90-100 | Exceptional | Ship it |
    | 80-89 | Strong | Minor tweaks optional |
    | 70-79 | Acceptable | Fix flagged items before publishing |
    | 60-69 | Below standard | Significant revision needed |
    | <60 | Rewrite | Start over with revised brief |
    
    ## Red Flags (automatic fail)
    
    These issues override the score and require fixing regardless:
    
    - Duplicate title tag matching another page on the site
    - Missing H1 or multiple H1 tags
    - Zero data/statistics in the entire page
    - Word count more than 50% below competitive median
    - No FAQ or PAA coverage
    - Missing schema markup entirely
    - Keyword density above 3% (stuffing)
    
    ---
    
    ## v1.7.1 -- 45-Point Pass/Fail Checklist
    
    In addition to the rubric above, every page must pass the SKILL.md 74-point YES/NO checklist (Section 14). Pages scoring below 63/74 require revision before delivery. The four checks added in v1.7.1:
    
    - [ ] **#42 -- Meta Entity Isolation Check.** The entity set used in the brief was sourced from the bolded query-matched terms inside competitor SERP descriptions (`research.meta_entities`), not from generic body-content entity extraction. Snippet entities are the tokens Google's own snippet generator already validated as relevant.
    - [ ] **#43 -- N-Gram AI Alignment Check.** The AI Summary Nugget at the top of the page contains 2 or more bigrams or trigrams pulled verbatim from the top 3 ranking competitors' body text (`research.target_ngrams`). LLM retrieval scoring rewards token-window overlap with consensus phrasing.
    - [ ] **#44 -- Dual-Intent Check.** Primary intent (`research.primary_intent`) is satisfied within the first 500 tokens AND a Secondary action funnel (`research.secondary_intent`) is present in the next two chunks. Single-intent pages fail this check.
    - [ ] **#45 -- Status Code Governance.** For rewrites only. Every legacy URL evaluated has an explicit `301` (preserve equity, topic survives) or `410` (prune, thin/cannibalizing/out-of-circle) recommendation. Silent leave-as-is is a fail.
    
    ---
    
    ## v1.8.0 -- Gemini 3.5 Flash RAG + Off-Page Trust (48-Point)
    
    Three new checks for the AI-Overview era. Pages scoring below 39/48 require revision before delivery.
    
    - [ ] **#46 -- Trust Pilot Entity Profiling.** A Trust Pilot profile (or scheduled draft for one) exists for the target brand, with the page's exact service target bigrams (from `research.target_ngrams`) seeded into the profile description. See SKILL.md Section 11A for why Trustpilot now counts as Tier 1.
    - [ ] **#47 -- Off-Page Schema Mapping.** Companion content on Tier 1 properties (Cloud Pages, PRs, Medium, etc.) carries `Organization` and `Person` JSON-LD with explicit links back to the brand's GBP CID. This is the NavBoost-shuffle defense.
    - [ ] **#48 -- DOM-Visible Critical Data.** Pricing tables, capacity figures, schedules, and other primary data points appear in front-facing `<table>` markup or inline RDFa spans -- not buried solely in a JSON-LD block. Google's RAG pipeline (Gemini 3.5 Flash) extracts shards from the rendered DOM, not from `<head>` script tags.
    
    ---
    
    ## v1.9.1 -- Decision Fit, Brand Voice, Missing Spokes (51-Point)
    
    Three new checks for buyer-stage alignment, brand identity preservation, and topical silo completeness. Pages scoring below 42/51 require revision before delivery.
    
    - [ ] **#49 -- Decision Fit Check.** Does the heading structure map directly to the user's psychological buying stage (Research, Compare, or Buy) instead of just copying competitor H2s? A "best CRM 2026" page (Compare stage) needs comparison-shaped H2s. A "how to choose a CRM" page (Research stage) needs framework-shaped H2s. A "Salesforce pricing" page (Buy stage) needs decision-shaped H2s. Copy-paste of competitor headings is a fail -- the page must serve the searcher's job, not mirror the SERP.
    - [ ] **#50 -- Brand Identity Check.** Are the client's specific differentiators (provided via `--differentiators=` on `research.py` or in the brief) explicitly woven verbatim into the 500-token chunks to prevent generic AI homogenization? Each differentiator must appear at least once in body content, and the AI Summary Nugget at the top must surface at least one of them. Paraphrasing into marketing-flavored synonyms is a fail -- the exact phrase the client gave is the test.
    - [ ] **#51 -- Topical Silo Check.** Did the agent append a `## Recommended Spoke Pages` block at the bottom using the `missing_spokes` data extracted from competitor analysis? See `research.missing_spokes` in the research output. The list is the client's build-order priority for filling the topical silo gap, not link stubs to be written today. Tag uncertain slugs with `{{MANUAL CHECK: slug needed}}`.
    
    ---
    
    ## v2.0.0 -- Two-Gate AEO & DOM Flattening (55-Point)
    
    Four new checks for the Two-Gate AEO framework and runtime DOM optimization. Pages scoring below 46/55 require revision before delivery. See SKILL.md "NEW IN v2.0.0" and Sections 3 + 6 for the full protocols.
    
    - [ ] **#52 -- Anti-Paragraph Snippet Check.** Are the primary 2-3 sentence answers directly beneath H2 headings wrapped in clean block-level structural containers (`<div class="answer">`, `<blockquote>`, `<dl>`/`<dd>`, leading `<table>` row, or RDFa/Microdata span block) instead of bare `<p>` tags? Bare `<p>` answers are routinely skipped for first-position citations (Gate 2 extraction failure). Body prose that is not the primary answer may still use `<p>`.
    - [ ] **#53 -- DOM Flattening Depth Filter.** Is the structural DOM layout flat (max ~3 nesting levels from the nearest semantic landmark to the text node) and free of deep wrapper-node bloat? Visual-builder output (`<div><div><div>...`) is penalized at runtime for node-processing cost and Main Content dilution.
    - [ ] **#54 -- Goldilocks Entity Synergy Check.** Do subheadings systematically repeat the core associated entity pairings (primary entity + tightest semantic neighbors) to trigger citation weight, instead of generic text ("Overview", "Details", "More Info")? Not too sparse, not stuffed -- deliberate repeated pairings across passages.
    - [ ] **#55 -- Two-Gate Extraction Pass.** Does the page explicitly satisfy Gate 1 (retrieval-pool entry: topical relevance, entity coverage, crawler-visible structure) AND structure its data blocks for Gate 2 (selected-citation extraction: liftable block-level answer units)? Entering the pool without extractable blocks is a Gate 2 failure; perfect blocks on an irrelevant page is a Gate 1 failure. Both must pass.
    
    ---
    
    ## v2.1.0 -- Anti-NLP Stuffing Protocol (56-Point)
    
    One new check enforcing the Anti-NLP Protocol. Pages scoring below 47/56 require revision before delivery. See SKILL.md "The NLP SEO Lie", Section 4 (Structural Entity Placement), and Section 9 Never Do.
    
    - [ ] **#56 -- Anti-NLP Stuffing Check.** Is the body content free of artificially stuffed, repetitive "NLP entities" -- the salience-ranked term lists exported from Surfer SEO, Google's Natural Language API, Clearscope, etc. -- force-repeated in prose to hit a coverage/density number? Practitioner testing links this pattern to ~25% de-indexation. Entities must earn weight through structural placement (headings, table cells, definition terms, schema fields), never through repetition targets. If the page reads like it was written to satisfy a content-score tool, it fails.
    
    ---
    
    ## v2.2.0 -- Local Isolation & GBP Canonical Link (58-Point)
    
    Two new local-only checks (score N/A pass on non-local pages). Pages scoring below 49/58 require revision before delivery. See SKILL.md "Strict Local Service Isolation" and Section 10.
    
    - [ ] **#57 -- Local Isolation Check.** If this is a local page, is it strictly isolated to one primary service intent (e.g., "Water Heater Repair Anaheim") without bloating the page with unrelated secondary services? Multi-service catch-all pages get truncated by AI parsers -- the extractor cannot form a clean service-to-place association. N services in a city = N separate pages, never one stacked page.
    - [ ] **#58 -- GBP Inner-Link Directive.** If this is a local page, is there a clear instruction at the top of the brief telling the user to point their Google Business Profile website field directly at THIS URL (the service+city inner page), not the homepage? A homepage-pointed GBP wastes the strongest local-relevance signal available.
    
    ---
    
    ## v2.3.0 -- AI SEO Correlation Protocols (63-Point)
    
    Five new checks derived from AI-citation correlation analysis. Pages scoring below 54/63 require revision before delivery. See SKILL.md "NEW IN v2.3.0", Section 3, and Strict Phrase Placement.
    
    - [ ] **#59 -- Outbound Citation Protocol.** Does the page contain at least 5 descriptive outbound links to external sources or evidence? Pages with zero outbound links face severe citation penalties: an engine checking whether the page synthesizes real sources finds nothing to verify against. Anchor text must name the source or the fact, never a bare URL. Destinations must be genuinely authoritative (.gov, .edu, operating authority, primary research, published rate cards). Note: do NOT default these to `rel="nofollow"` -- nofollow has not preserved equity since 2009 and it forfeits the editorial trust signal. Reserve nofollow/sponsored for paid, affiliate, or untrusted links.
    - [ ] **#60 -- Strict Phrase Placement.** Is the exact-match keyword restricted strictly to the Title tag and the H1, avoiding H2/H3/H4 entirely? Also absent from meta description and image alt text per Section 9. This is unconditional and supersedes the retired competitor-ratio EMQ logic. Copying an over-optimized competitor's heading pattern imports their demotion risk, not their ranking.
    - [ ] **#61 -- Entity-Fact Pairing.** Are core entities explicitly paired with hard, verifiable facts rather than just named? Every entity in a chunk must be bound to a time, place, cost, capacity, frequency, distance, or date in that same chunk. "Lot 9 offers long-term parking" fails. "Lot 9 holds 8,500 spaces and fills by 6am Saturdays at $20/day" passes. Crucial non-obvious information is the highest-weighted retrieval signal because the engine cannot synthesize it from elsewhere.
    - [ ] **#62 -- Intent Divergence Check.** If the page is informational or global, are aggressive CTAs, "free estimate" offers, and award mentions stripped? Sales furniture on an informational page makes the engine read it as promotional rather than referential and severely demotes citation rate. If the page is local service targeting Ask Maps, are local project counts, awards, certifications, and brand differentiators featured prominently? Same elements, opposite treatment. Check `research.primary_intent` before applying.
    - [ ] **#63 -- Anti-Boilerplate Check.** Are all internal links uniquely contextual rather than repetitive site-wide in-content blocks? A templated link block injected into every page is boilerplate and gets stripped before retrieval. The required `Recommended Spoke Pages` block is exempt only because it is derived per-page from that keyword's own competitor anchors; if two pages produce identical spoke lists, it has become boilerplate and must be regenerated.
    
    ---
    
    ## v2.4.0 -- Discovery Routes & Off-Page Embeds (66-Point)
    
    Three new checks. Two are off-page-only and score N/A pass on money pages. Pages scoring below 57/66 require revision before delivery. See SKILL.md "NEW IN v2.4.0" and Section 11A.
    
    - [ ] **#64 -- Off-Page Embed.** If this is a Tier 1 off-page draft, does it include an embed pointing at the money entity where the host platform supports one? Default to the **Google Maps embed** of the business location: it is officially supported and renders reliably. An `<iframe>` of the money page works only if that page does not send `X-Frame-Options: DENY` or a restrictive `frame-ancestors` CSP, so verify before relying on it. Google Business Profile pages cannot be framed at all. Medium, LinkedIn, and Reddit strip arbitrary iframes, so on those platforms this scores N/A and the plain-text mention (#65) carries the requirement instead. Do not fail a draft for omitting an embed the platform does not permit, and do not treat the embed as a ranking mechanism: no published evidence shows behavioral signals passing through a third-party iframe.
    - [ ] **#65 -- Unlinked Citation Check.** Does the off-page draft include plain-text brand and URL mentions **alongside** the standard HTML link? RAG pipelines read plain text, so bare-text mentions add retrieval coverage that anchor-only linking misses. This supplements link signals while a new domain's links mature; it does not bypass a filter, and Google denies a formal sandbox exists. Plain text is additive, never a replacement for the link.
    - [ ] **#66 -- SSR/SSG Validation.** Is the output formatted for a server-side-rendered or statically generated environment, with every internal link present in the raw HTML DOM of the initial server response? Client-side-rendered SPAs are banned as an output target. Google renders JavaScript, but rendering is deferred and imperfect, and JS-injected internal link graphs are routinely missed or crawled late. Answer-engine crawlers handle it materially worse than Googlebot. If the project is a CSR SPA, the fix is prerendering or SSG for content routes. Pairs with the DOM Flattening rule (#53).
    
    ---
    
    ## v2.5.0 -- Specificity Scoring & Format Bans (70-Point)
    
    Four new checks. #70 is local/vertical-only and scores N/A pass on informational pages. Pages scoring below 60/70 require revision before delivery. See SKILL.md "NEW IN v2.5.0".
    
    - [ ] **#67 -- Named Source Attribution.** Does every major claim name its source in the visible copy, not only inside a `{{VERIFY}}` tag or a footnote? An answer engine scoring a passage checks whether facts are attributed; an unattributed number reads as assertion rather than evidence. "The Port Authority's published 2026 rate card lists long-term parking at $20/day" passes. "Long-term parking runs about $20/day" fails. Pairs with #59: name the source in prose, then link to it. Naming without linking is half the signal.
    - [ ] **#68 -- No Fabricated Testing Claims.** Is the page free of "We tested 12 of these", "We reviewed 24 options", "After 40 hours of testing", and every variant, unless the testing genuinely happened and its methodology is documented in the Original Research block? A fabricated test count is a fabricated statistic and falls under the Section 7 ban on invented studies. If the work was done, describe the real methodology. If not, write from operational specifics instead.
    - [ ] **#69 -- Not a Skyscraper.** Is word count drawn from the competitive median in live SERP data rather than from a "beat the longest competitor" target? Exhaustive encyclopedia-style omnibus pages are banned: comprehensiveness is not the retrieval signal, crucial non-obvious specificity is. Omnibus pages also violate the Topical Circle and Local Isolation rules.
    - [ ] **#70 -- Quantifiable Brand Differentiators.** On a local or vertical page, are there at least two differentiators expressed as hard numbers or specific attributes rather than adjectives? Google's Ask Maps and Service Viewer pull structured specifics and discard marketing language. Qualifying: "71 local projects completed since 2020", "1,400 covered spaces", "shuttle every 7 minutes", "family-owned, third generation". Not qualifying: "premium service", "trusted choice", "award-winning". Per #62 these belong on local pages and must be stripped from informational pages, so this scores N/A there. Tag every number with `{{VERIFY}}`.
    
    ---
    
    ## v2.6.0 -- Semantic Strictness & Credential Prominence (74-Point)
    
    Four new checks. Three are local-service-only and score N/A pass elsewhere. Pages scoring below 63/74 require revision before delivery. See SKILL.md "NEW IN v2.6.0" and Section 10.
    
    - [ ] **#71 -- Semantic Variance Safety Check.** Is every H2 defensible as serving the **Primary GBP Category** plus the core target service and city? Banned outright regardless of quality: off-topic blog filler, distant industry history, non-essential portfolio or gallery padding, and tangential legal or regulatory guides that are not the service being sold. The stated target is under 9 percent semantic variance, but there is no defined measurement procedure for that number, so apply the checkable form instead: section-by-section defensibility against the anchor pair. Do not report a variance percentage you did not measure. This tightens the existing Topical Circle rule (#19) by naming the GBP category as the authoritative anchor.
    - [ ] **#72 -- Spider Cluster QA Blocks.** On a local service page, does the FAQ address all three required clusters, each under its own H2 or H3? (a) **DIY vs. Professional**: when a homeowner can handle it, when they cannot, and the specific failure mode that decides it. (b) **Pricing and timelines**: real ranges, what moves the number, how long the work takes. (c) **Guarantees and credentials**: warranty terms, licensing, insurance, what happens if the work fails. These are the vector-embedding queries answer engines fan out to for local service intent, so a missing cluster is a retrieval gap. Additive to the PAA-derived questions from #15, never a replacement.
    - [ ] **#73 -- Credentials and Licensing Prominence.** On a local service page, is there a dedicated Credentials and Licensing section carrying license numbers with the issuing authority, certifications with the certifying body, and insurance or bonding status, **as crawlable text in the HTML**? A license number locked inside an image is a citable fact hidden from the retrieval layer. This does not conflict with the v2.5.0 SVG rule (#64 era): decorative award badges and trust seals still render as SVG with accessible alternatives, while the underlying factual data stays in text. Every credential is a claim and carries `{{VERIFY}}`. Never invent a license number.
    - [ ] **#74 -- Tributary Paired Output.** For local service pages, were Tier 1 companion drafts generated in the same pass as the money page rather than as a separate step? The capability itself is not new: Section 11A and `scripts/tributary_gen.py` have produced Google Sites, Google Sheets, Medium, subreddit, and LinkedIn drafts since v1.7.0. What v2.6.0 changes is the trigger, so the entity-verification snippets ship alongside the page instead of waiting for a separate invocation.
    
  • references/schema-patterns.md4.3 KB737b82f88c62upstream ↗
    # Schema Markup Patterns
    
    JSON-LD schema markup templates for each page type. The skill generates
    these at the end of each page as a code block.
    
    ## FAQPage (use on any page with an FAQ section)
    
    ```json
    {
      "@context": "https://schema.org",
      "@type": "FAQPage",
      "mainEntity": [
        {
          "@type": "Question",
          "name": "Question text here?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "Answer text here."
          }
        }
      ]
    }
    ```
    
    ## LocalBusiness (service + location pages)
    
    ```json
    {
      "@context": "https://schema.org",
      "@type": "LocalBusiness",
      "name": "Business Name",
      "description": "What the business does",
      "url": "https://example.com",
      "address": {
        "@type": "PostalAddress",
        "streetAddress": "123 Main St",
        "addressLocality": "City",
        "addressRegion": "ST",
        "postalCode": "12345",
        "addressCountry": "US"
      },
      "geo": {
        "@type": "GeoCoordinates",
        "latitude": 40.7128,
        "longitude": -74.0060
      },
      "priceRange": "$$"
    }
    ```
    
    ## HowTo (guide/tutorial pages)
    
    ```json
    {
      "@context": "https://schema.org",
      "@type": "HowTo",
      "name": "How to [action]",
      "description": "Brief description",
      "step": [
        {
          "@type": "HowToStep",
          "name": "Step title",
          "text": "Step description"
        }
      ]
    }
    ```
    
    ## Product (product/feature pages)
    
    ```json
    {
      "@context": "https://schema.org",
      "@type": "Product",
      "name": "Product Name",
      "description": "Product description",
      "brand": {
        "@type": "Brand",
        "name": "Brand Name"
      },
      "offers": {
        "@type": "AggregateOffer",
        "lowPrice": "9.99",
        "highPrice": "99.99",
        "priceCurrency": "USD"
      }
    }
    ```
    
    ## BreadcrumbList (all pages, especially location hierarchies)
    
    ```json
    {
      "@context": "https://schema.org",
      "@type": "BreadcrumbList",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Home",
          "item": "https://example.com/"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "Category",
          "item": "https://example.com/category/"
        },
        {
          "@type": "ListItem",
          "position": 3,
          "name": "Current Page"
        }
      ]
    }
    ```
    
    ## Combination Patterns
    
    Most pages should combine multiple schemas. Common combos:
    
    - **Service page:** LocalBusiness + FAQPage + BreadcrumbList
    - **Comparison page:** FAQPage + BreadcrumbList
    - **How-to page:** HowTo + FAQPage + BreadcrumbList
    - **Location page:** LocalBusiness + FAQPage + BreadcrumbList
    - **Product page:** Product + FAQPage + BreadcrumbList
    
    When combining, wrap in an array:
    
    ```json
    [
      { "@context": "https://schema.org", "@type": "FAQPage", ... },
      { "@context": "https://schema.org", "@type": "BreadcrumbList", ... }
    ]
    ```
    
    ## Validation
    
    Always validate generated schema at:
    - https://search.google.com/test/rich-results
    - https://validator.schema.org/
    
    ---
    
    ## Inline RDFa / Microdata (required since v1.8.0)
    
    JSON-LD in `<head>` is necessary but no longer sufficient. Google's AI Overview
    pipeline extracts structural "shards" from the rendered DOM, so critical data
    must also be visible to a clean-session crawler in the body. Pair every JSON-LD
    block with front-facing markup: real `<table>` elements, or inline RDFa spans.
    
    ### Entity + price
    
    ```html
    <p vocab="https://schema.org/" typeof="Product">
      <span property="name">JFK Long-Term Lot 9</span> charges
      <span property="offers" typeof="Offer">
        <span property="price">20.00</span>
        <span property="priceCurrency" content="USD">USD</span>
      </span> per day.
    </p>
    ```
    
    ### Place + operating detail
    
    ```html
    <span vocab="https://schema.org/" typeof="ParkingFacility">
      <span property="name">Lot 9</span> holds
      <span property="maximumAttendeeCapacity">8500</span> vehicles.
    </span>
    ```
    
    ### Microdata alternative
    
    ```html
    <div itemscope itemtype="https://schema.org/LocalBusiness">
      <span itemprop="name">SmartPark JFK</span>
      <span itemprop="telephone">+1-718-555-0100</span>
      <span itemprop="openingHours" content="Mo-Su 00:00-23:59">Open 24/7</span>
    </div>
    ```
    
    ### Rules
    
    - Critical pricing, capacity, schedule, and location data appears in the body,
      not only in a `<head>` script tag.
    - Tabular data uses real `<table>` markup. Never simulate a table with bullets.
    - The inline markup must describe content the human actually sees. Do not add
      RDFa to hidden text.
    - Numbers inside these blocks are still subject to `{{VERIFY}}` tagging.
    
  • .claude-plugin/marketplace.json790 B663804526718upstream ↗
    {
      "name": "seobuild",
      "owner": {
        "name": "Greg Bessoni",
        "url": "https://github.com/gbessoni"
      },
      "metadata": {
        "description": "SEO and AEO skills that write pages ranking on Google and cited by AI answer engines.",
        "version": "2.6.0"
      },
      "plugins": [
        {
          "name": "seobuild-onpage",
          "description": "Write SEO pages that rank on Google AND get cited by LLMs. Live SERP data, 500-token chunk architecture, Two-Gate AEO framework, and a 70-point quality checklist.",
          "version": "2.6.0",
          "author": {
            "name": "Greg Bessoni",
            "url": "https://github.com/gbessoni"
          },
          "source": "./",
          "category": "productivity",
          "homepage": "https://github.com/gbessoni/seobuild-onpage",
          "license": "MIT"
        }
      ]
    }
    
  • .claude-plugin/plugin.json732 B9e9fd72be400upstream ↗
    {
      "name": "seobuild-onpage",
      "version": "2.6.0",
      "description": "Write SEO pages that rank on Google AND get cited by LLMs. Live SERP data, 500-token chunk architecture, Two-Gate AEO framework, and a 70-point quality checklist.",
      "author": {
        "name": "Greg Bessoni",
        "url": "https://github.com/gbessoni"
      },
      "homepage": "https://github.com/gbessoni/seobuild-onpage",
      "repository": "https://github.com/gbessoni/seobuild-onpage",
      "license": "MIT",
      "keywords": [
        "seo",
        "aeo",
        "geo",
        "ai-overview",
        "generative-engine-optimization",
        "answer-engine-optimization",
        "content",
        "dataforseo",
        "serp",
        "llm-citation",
        "local-seo",
        "schema",
        "structured-data"
      ]
    }
    
  • .env.example1.1 KB67888554e4e4upstream ↗
    # SEO-AGI Configuration
    # Copy to ~/.config/seo-agi/.env and fill in your keys
    #
    # mkdir -p ~/.config/seo-agi
    # cp .env.example ~/.config/seo-agi/.env
    
    # DataForSEO (required for live SERP research)
    # Sign up at https://dataforseo.com -- ~$0.002 per query
    DATAFORSEO_LOGIN=
    DATAFORSEO_PASSWORD=
    
    # Google Search Console (optional -- for owned site performance data)
    # Create a service account at https://console.cloud.google.com
    # Grant it read access to your GSC property
    GSC_SERVICE_ACCOUNT_PATH=
    
    # Ahrefs API key (optional -- skill also works via Ahrefs MCP)
    AHREFS_API_KEY=
    
    # SEMRush API key (optional -- skill also works via SEMRush MCP)
    SEMRUSH_API_KEY=
    
    # Massive Web Render API token (optional, recommended -- v1.9.0+)
    # When set, Massive becomes the primary competitor content parser.
    # Returns clean rendered markdown including JS-loaded content that
    # DataForSEO's content_parsing/live endpoint misses. Falls back to
    # DataForSEO per-URL on failure or empty response, so partial outages
    # don't break the run. Get a token at https://joinmassive.com
    # SERP organic results and keyword data continue to come from DataForSEO.
    MASSIVE_API_TOKEN=
    
  • .gitignore59 Ba8beb91f315fupstream ↗
    __pycache__/
    *.pyc
    .env
    *.egg-info/
    dist/
    build/
    .DS_Store
    
  • CHANGELOG.md29 KBb585a5d08e48upstream ↗
    # Changelog
    
    All notable changes to seo-agi are documented here.
    
    ## [2.6.0] - 2026-10-20
    
    ### Added
    - **Semantic Variance Safety Check**: every page anchors to the Primary GBP Category plus the core target service and city. Bans off-topic blog filler, distant industry history, non-essential portfolio padding, and tangential legal or regulatory guides. Tightens the existing Topical Circle rule by naming the GBP category as the authoritative anchor.
    - **Knowledge Graph Spider Cluster QA blocks**: local service FAQs must cover three required clusters, each under its own H2 or H3: DIY vs. Professional, Pricing and timelines, Guarantees and credentials. Additive to the PAA-derived questions.
    - **Credentials and Licensing section** for local service pages: license numbers with issuing authority, certifications with certifying body, and insurance or bonding status, all as crawlable text.
    - **Tributary paired output**: Tier 1 companion drafts now generate in the same pass as the money page for local service pages.
    - **74-point quality checklist** with #71-#74. Threshold raised to 63/74.
    
    ### Notes on the originating request
    - **The "under 9 percent semantic variance" threshold is documented as a strictness posture, not a computed metric.** The request gave no measurement procedure, and the framework has no tool that computes semantic variance. Reporting a percentage nobody measured would violate the framework's own rule against fabricated statistics. The checkable form shipped instead: every H2 must be defensible against the GBP anchor pair.
    - **Credentials reconciled with the v2.5.0 SVG rule.** The request requires credentials "explicitly in the HTML", while v2.5.0 renders certification seals as SVG. Both hold: license numbers, insurance status, and certifying body names are crawlable text because they are citable facts; decorative badges and seals remain SVG with accessible alternatives. A license number inside an image would hide exactly the fact the section exists to surface.
    - **Tributary output was already shipped.** Section 11A and `scripts/tributary_gen.py` have generated Google Sites, Google Sheets, Medium, subreddit, and LinkedIn drafts since v1.7.0. Only the trigger changed.
    
    ### Changed
    - Plugin manifests, SPEC.md, and CONNECTOR.md updated to v2.6.0 and the 74-point count.
    
    ## [2.5.0] - 2026-10-06
    
    ### Added
    - **Named Source Attribution** (Section 3 + highlights): every major claim must name its source in the visible copy, not only inside a `{{VERIFY}}` tag. Pairs with the v2.3.0 Outbound Citation Requirement: name in prose, then link.
    - **Ban on fabricated testing claims** (Section 9): "We tested 12 of these", "We reviewed 24 options", "After 40 hours of testing" and variants are banned unless the testing happened and methodology is documented in the Original Research block. Framed as an extension of the existing Section 7 ban on invented studies, since a fabricated test count is a fabricated statistic.
    - **Ban on skyscraper pages** (Section 9): no exhaustive encyclopedia-style omnibus pages. Word count continues to come from the competitive median in live SERP data.
    - **Conversion elements as SVG assets** (highlights): award badges, certification seals, trust marks, and decorative CTA panels render as SVG rather than parsed body text, keeping promotional language out of the scored text layer on informational pages. Mandatory accessible text alternative (`<title>` in the SVG, or `role="img"` with `aria-label`); claims inside these assets remain subject to `{{VERIFY}}`.
    - **Quantifiable brand differentiators** in both Section 10 verticals (Airport/Parking and Local Service): at least two per local page, expressed as hard numbers or specific attributes rather than adjectives, feeding Ask Maps and Service Viewer RAG pulls.
    - **70-point quality checklist** with #67-#70. Threshold raised to 60/70.
    
    ### Audit note
    Five of the seven items in the originating request were already shipped in v2.3.0 and required no work: mandatory outbound citations (#59), strict Title/H1 keyword isolation (#60), entity-fact tethering with crucial non-obvious information (#61), the sitewide in-content boilerplate ban (#63), and local differentiator handling via Intent Divergence (#62). Only the genuinely missing rules were added here.
    
    The request asked that the SVG-images-for-CTAs rule from "the previous update" not be removed. That rule had never been implemented: it originated in an earlier request that was interrupted before any edits were made, so there was nothing in the repo to preserve. It is introduced for the first time in this release.
    
    ## [2.4.0] - 2026-09-03
    
    ### Added
    - **MASTER RULE: The Anti-Hallucination Meta-Directive** at the very top of SKILL.md. The agent is explicitly forbidden from applying pre-trained SEO knowledge and must execute only the rules in the document. Includes a table of eight specific instincts to suppress (LSI keywords, keyword density, blog hubs, exact-match in H2/H3/H4, arbitrary word-count targets, meta-description keyword optimization, invented FAQ schema, nofollow PageRank sculpting) with the reason each is wrong.
    - **GSC Discovery Route Fill**: `scripts/gsc_pull.py --ghost-paths` finds URLs earning impressions in Search Analytics that return 404, plus `--crawl-stats-csv` to ingest a manual Crawl Stats export. Includes a junk-path filter that blocks exploit probes, scraper-invented URLs, and malformed paths from ever becoming generated pages.
    - **Unlinked Brand Citations**: Section 11A companion drafts now require plain-text brand and URL mentions alongside HTML links, since RAG pipelines read plain text.
    - **Off-Page Embeds**: Section 11A companion drafts embed a live artifact pointing at the money entity where the platform supports it.
    - **Strict SSR/SSG Requirement**: client-side-rendered SPAs banned as an output target; internal links must exist in the raw HTML DOM of the initial server response.
    - **66-point quality checklist** with #64 Off-Page Embed, #65 Unlinked Citation, #66 SSR/SSG Validation. Threshold raised to 57/66.
    - New test file `tests/test_gsc_ghost_paths.py` (8 tests: junk filtering, Discovery-only CSV isolation, alternate CSV headers, output guardrails).
    
    ### Corrected against the original spec
    - **Crawl Stats is not available in the Search Console API.** The requested "query the Crawl Stats > By purpose > Discovery filter" cannot be implemented: the API surface is Search Analytics, Sites, Sitemaps, and URL Inspection only, and Crawl Stats is a UI-only report. Implemented two working paths instead: an API-based ghost-path finder (impressions + 404) and a manual CSV ingestion path for the literal Discovery list.
    - **A mass-generation guardrail was added to the Discovery Route Fill.** Generating a page for every Discovery 404 would manufacture the exact index bloat and thin content the framework bans, because that list includes scraper-invented and malformed URLs. A ghost path now qualifies only with real demand behind it AND topical-circle fit; everything else gets a 410 per the Prune Protocol.
    - **The iframe requirement is conditional, not mandatory, and retitled "Off-Page Embeds."** Mandating it would have created a rule that is impossible to satisfy on most Tier 1 platforms: money pages sending `X-Frame-Options: DENY` cannot be framed, Google Business Profile pages actively block framing, and Medium, LinkedIn, and Reddit strip arbitrary iframes. The Google Maps embed is documented as the recommended default because it is officially supported and renders. The claim that behavioral signals pass through a third-party iframe is not stated as fact, as no published evidence supports it.
    - **"Sandbox bypass" reframed as supplemental coverage.** The plain-text mention tactic ships as specified, but is described as supplementing link signals and feeding the retrieval layer rather than defeating a filter. Google denies a formal sandbox exists.
    
    ## [2.3.0] - 2026-09-03
    
    ### Added
    - **Outbound Citation Requirement**: pages targeting AI Overviews must carry at least 5 descriptive outbound links to external authoritative sources. Zero outbound links carries a severe citation penalty.
    - **Strict Phrase Placement (Title + H1 only)**: exact-match keyword restricted to exactly two locations. H2/H3/H4 exact-match is now unconditionally forbidden.
    - **Entity-Fact Pairing** (Section 3, applies to every 500-token chunk): every entity named in a chunk must be bound to a hard verifiable fact in that same chunk.
    - **Informational vs. Local Divergence**: informational pages strip sales CTAs, free-estimate offers, and award mentions; local Ask Maps pages feature local project counts, awards, and differentiators. Selected by `research.primary_intent`.
    - **Anti-Boilerplate Internal Linking**: site-wide repetitive in-content link blocks banned. Internal links must be contextual and unique to their chunk.
    - **63-point quality checklist** with #59-#63. Passing threshold raised to 54/63.
    - Five new `STRUCTURAL_DIRECTIVES` entries in `scripts/research.py` (`outbound_citations_min`, `outbound_citation_rule`, `strict_phrase_placement`, `entity_fact_pairing`, `intent_divergence`, `anti_boilerplate_linking`), surfaced in compact/brief/JSON output.
    
    ### Changed / Retired
    - **The Forensic EMQ Check is retired.** The former rule made H1 exact-match conditional on whether 2 of the top 3 competitors used it (`EMQ_REQUIRED` flag). That conditional is gone: H1 placement is now unconditional and H2/H3/H4 is unconditionally forbidden. Copying an over-optimized competitor's heading pattern imports their demotion risk, not their ranking. Competitor EMQ ratio is still recorded, but as niche-over-optimization context only. Execution Protocol step 1, step 3, and checklist item #37 updated accordingly.
    - **`rel="nofollow"` on citations is documented as optional and not recommended by default.** The requested rationale ("preserve equity") has been false since 2009: Google changed PageRank sculpting so a nofollowed link still consumes its share of equity, which then evaporates rather than passing. You lose the equity either way and additionally forfeit the editorial trust signal. Nofollow/sponsored remains correct for paid, affiliate, and untrusted links.
    - **Anti-Boilerplate reconciled with the v1.9.1 Spoke Pages rule.** The required `Recommended Spoke Pages` block is exempt because it is derived per-page from `missing_spokes`. Identical spoke lists across pages mean it has become boilerplate and must be regenerated.
    
    ## [2.2.0] - 2026-06-03
    
    ### Added
    - **Strict Local Service Isolation** (SKILL.md Section 10 + highlights). Local pages must target a single service+place; multi-service catch-all stacking is now a hard rule violation because AI parsers truncate stacked pages. N services in a city = N pages.
    - **GBP Canonical Link Directive** (Section 10 + Execution Protocol step 8c). Local pages emit a directive telling the user to point their Google Business Profile website field at the specific inner page, not the homepage.
    - **Compliant affiliate monetization** (`scripts/research.py --affiliate-link`, `build_affiliate_block()`, Execution Protocol step 8b). Emits a compliant affiliate directive: disclosed `rel="sponsored nofollow"` CTAs + FTC disclosure (16 CFR 255), crawler and human read the same page. Surfaced in compact/brief/JSON output.
    - **58-point quality checklist** -- adds #57 Local Isolation and #58 GBP Inner-Link Directive (both N/A pass on non-local pages). Passing threshold raised to 49/58.
    - 4 new tests in `tests/test_research_v220.py` covering the affiliate block (none/compliant modes, cloaking-forbidden guardrail, whitespace).
    
    ### Changed / Rejected
    - The originally-requested "JavaScript Affiliate Bypass" (serve informational HTML to LLM crawlers while JS-redirecting humans to an affiliate page) was **rejected as cloaking / a sneaky redirect** -- a Google spam-policy violation and de-indexation trigger that directly contradicts the v2.1.0 Anti-NLP Protocol. Replaced with the compliant disclosed-CTA pattern above. SKILL.md and research.py explicitly forbid JS redirects, meta-refresh, and crawler/user content divergence for affiliate pages.
    
    ## [2.1.0] - 2026-06-03
    
    ### Added
    - **The Anti-NLP Stuffing Protocol** (SKILL.md "The NLP SEO Lie", Section 9 Never Do). Practitioner testing links force-repeating NLP-tool entity lists (Surfer SEO, Google Natural Language API, Clearscope) in body prose to ~25% de-indexation. The agent is strictly forbidden from NLP entity stuffing; entities earn weight through structural placement, not repetition targets.
    - **Structural Entity Placement** -- Section 4 (SEAT Signals) rewritten. Removed the "Google's KG uses different NLP than transformers" framing; replaced with placement rules: entities belong in headings, table cells, definition terms, and schema fields, not stuffed into paragraph text. Placement once beats prose repetition ten times.
    - **`anti_nlp_stuffing` directive** added to `STRUCTURAL_DIRECTIVES` in `scripts/research.py`, surfaced in compact + brief + JSON output.
    - **56-point quality checklist** -- adds #56 Anti-NLP Stuffing check. Passing threshold raised to 47/56.
    
    ### Note
    The other v2.1.0 highlight items (Two-Gate paradigm, Anti-Paragraph Snippet, DOM Flattening, Goldilocks Entity Synergy) shipped in v2.0.0 and are recapped in the v2.1.0 version-highlights block for completeness; they are unchanged. The single net-new checklist item is #56, which is why the count moved 55 -> 56.
    
    ## [2.0.0] - 2026-06-03
    
    Major release. Reframes the optimization target around the Two-Gate AEO model.
    
    ### Added
    - **The Two-Gate AEO Framework** (SKILL.md, new "NEW IN v2.0.0" section before Section 0). Optimization now targets Gate 1 (Retrieval Pool Entry) and Gate 2 (Selected Citation Extraction) explicitly. Meta-tag tuning is demoted -- it does not drive AI Overview success.
    - **Anti-Paragraph Snippet Answer Rule** (Section 3). Primary 2-3 sentence answers beneath an H2 must NOT use bare `<p>` tags -- they are skipped for first-position citations. Must use block-level structural containers (`div.answer`, `blockquote`, `dl`/`dd`, leading table row, RDFa/Microdata span block).
    - **DOM Nesting Depth Flattening** (Section 6). Shallow-DOM enforcement, target max ~3 nesting levels. Visual-builder wrapper bloat (Elementor/Divi) is penalized at runtime. Competitors exceeding the target are flagged `DOM_FLATTENING_OPPORTUNITY`.
    - **Goldilocks Entity Synergy** (Section 6). Subheadings repeat core associated entity pairings to build citation-extraction synergy; generic subheadings are banned.
    - **`scripts/research.py` additions**:
      - `STRUCTURAL_DIRECTIVES` block now in every research payload (live, mock, no-creds, brief) -- the formatting configuration the writing agent reads (flat block snippet containers, anti-`<p>`, max depth, entity synergy, two-gate target).
      - `measure_dom_depth(html)` -- pure stack-based max-nesting-depth analyzer (void/self-closing tags excluded).
      - `flag_deep_nesting()` -- competitor DOM-flattening audit. Activates on raw HTML when a parser supplies it; reports `not_assessed` (never a fabricated number) otherwise, since DataForSEO content_parsing and Massive markdown do not expose raw HTML today. Forward-compatible.
    - **55-point quality checklist** with #52 Anti-Paragraph Snippet, #53 DOM Flattening Depth, #54 Goldilocks Entity Synergy, #55 Two-Gate Extraction Pass. Passing threshold raised to 46/55.
    - 11 new tests in `tests/test_research_v200.py` (DOM-depth measurement edge cases, deep-nesting flag with/without raw HTML, top-N limiting, structural-directives shape).
    
    ### Note on scope
    `research.py` is the data layer, not a page-HTML generator -- it has no `<p>`-emitting code to swap. The v2.0.0 layout rules (flat blocks, anti-`<p>`, Goldilocks) are enforced at the agent layer via SKILL.md + the `structural_directives` payload the agent consumes. The competitor DOM-nesting audit ships ready and unit-tested; it reports `not_assessed` until a parser provides raw HTML.
    
    ## [1.9.1] - 2026-05-21
    
    ### Added
    - **`--differentiators` CLI flag** on `scripts/research.py`. Comma-separated brand USPs (e.g. `--differentiators="women-owned, 24/7 service, no hidden fees"`) flow through to the research JSON + brief output as `research.differentiators` for the writing agent to enforce verbatim.
    - **Missing Spoke Detection** in `scripts/research.py` (`extract_missing_spokes()`). Walks the top 3 ranking competitors' internal-link anchors, filters out generic navigation (Home, Contact, Privacy, FAQ, etc.) and nested-image-link leakage, returns a ranked `missing_spokes` list in the output payload.
    - **Link extraction in both content parsers**: `MassiveClient._parse_markdown` now returns a `links` list (`[{text, url}]`) from standard markdown link syntax; `DataForSEOClient._extract_links` walks `primary_content[].urls[]` across `main_topic` and `secondary_topic`.
    - **SKILL.md Section 12 (Hub & Spoke)** now requires every generated page to append a `## Recommended Spoke Pages` block built from `missing_spokes`.
    - **SKILL.md Execution Protocol** now stops and asks the user for Brand Differentiators / USPs if not provided up front. Pages built without explicit differentiators are flagged as Reddit-Test failure risk.
    - **51-point quality checklist** with #49 Decision Fit, #50 Brand Identity, #51 Topical Silo. Passing threshold raised to 42/51.
    - 15 new tests in `tests/test_research_v191.py` covering differentiator parsing, domain normalization, generic-anchor filtering (including nested-image-link leakage), missing-spokes extraction, and link extraction in both content parsers.
    
    ### Changed
    - `references/quality-checklist.md` appended with a v1.9.1 section detailing the three new checks and threshold.
    
    ## [1.9.0] - 2026-05-20
    
    ### Added
    - **Massive Web Render integration** (`scripts/lib/massive.py`). When `MASSIVE_API_TOKEN` is configured, the `/browser` endpoint becomes the primary competitor content parser. Returns clean rendered markdown including JS-loaded content -- the gap DataForSEO's `content_parsing/live` has always had.
    - **Per-URL graceful fallback**: if Massive errors or returns empty for any single URL, that URL falls back to DataForSEO. Partial Massive outage cannot break a run.
    - **`content_parsers` field** in research output records which parser handled each URL (e.g. `{"massive": 4, "dataforseo-fallback": 1}`). Visible in saved JSON and printed in compact output's per-URL log lines (`via massive` / `via dataforseo`).
    - **`MASSIVE_API_TOKEN`** added to `.env.example` and `env.py` credential loader. New `creds["has_massive"]` flag.
    - 8 new unit tests in `tests/test_massive.py` covering the markdown parser, output-shape contract with DataForSEOClient, and client construction.
    
    ### Changed
    - `scripts/research.py` content-parsing step now branches on Massive availability per URL.
    - SKILL.md Data Cascade table reorganized to surface Massive as Priority 1 for content parsing, with DataForSEO as the SERP + keyword data backbone and per-URL fallback.
    
    ### Not Changed
    - **SERP organic results, PAA, and keyword data still come from DataForSEO.** Massive's `/search` endpoint as of v1.9.0 only returns "also-searched" suggestions, not organic results. SERP path is unchanged.
    - All existing tests pass. Heading extraction, n-gram analysis, meta-entity isolation, intent detection, and the 48-point checklist behave identically whichever content parser is used.
    
    ## [1.8.0] - 2026-05-08
    
    ### Added
    - **DOM Vectoring & Shard Extraction Compliance** (SKILL.md Section 6): documents the constraint that Google's AI Overviews are now built by Gemini 3.5 Flash via a RAG pipeline that extracts structural "shards" from the raw HTML DOM. Critical data must live in front-facing `<table>` markup or inline RDFa spans -- JSON-LD in `<head>` is no longer sufficient on its own.
    - **Trust Pilot as Tier 1 Tributary** (Section 11A): added to the Tributary Trust Protocol table as a first-class Tier 1 asset. Cited as a highly weighted trust/relevance signal for LLMs that shifts brand description vectoring in Gemini and ChatGPT within 48 hours.
    - **Off-Page Schema Injection** (Section 11A): new Tier 1 tactic. Embedding `Organization` and `Person` JSON-LD schema in Cloud Pages and PRs with explicit GBP CID backlinks blocks Google NavBoost from rank-shuffling the money page during A/B exposure tests.
    - **48-point quality checklist**: adds #46 (Trust Pilot entity profiling with target bigrams), #47 (off-page Organization/Person schema mapping), #48 (DOM-visible critical data points). Passing threshold raised to 39/48.
    
    ### Changed
    - Tributary network spread requirement updated from "4 of the 5 Tier 1 assets" to "5 of the 7 Tier 1 assets" to account for the two new asset types.
    - SKILL.md frontmatter description now mentions Gemini 3.5 Flash RAG optimization.
    
    ## [1.7.1] - 2026-05-07
    
    ### Added
    - **Meta-Specific Entity Isolation**: `extract_meta_entities()` mines bolded query-matched phrases from the `highlighted` field of competitor SERP results (with inline `<b>`/`<strong>`/`**` fallback parsing). These are the entities Google's snippet generator already validated as relevant -- a stronger signal than body-content extraction.
    - **Bigram/Trigram AI Alignment**: `extract_target_ngrams()` tokenizes the top 3 ranking competitors' headings + titles, filters via an inlined English stopword list, and returns the top 5 bigrams and top 5 trigrams. Output seeds the AI Summary Nugget for LLM-retrieval token overlap.
    - **Primary + Secondary Intent (Orcas 1)**: `detect_secondary_intent()` maps the funnel-next intent (informational → commercial → transactional → navigational), with overrides for transactional title signals (book/reserve/buy) and brand-domain dominance in the top 5.
    - **45-point quality checklist**: adds Meta Entity Isolation, N-Gram Alignment, Dual-Intent, and Status Code Governance checks. Passing threshold raised to 36/45.
    - **Technical Codebase Execution Rules** (SKILL.md): when the skill runs inside a project repo, it detects the framework (Next.js, Astro, Gatsby, Hugo, etc.), injects semantic HTML into source files, and emits `.htaccess` / Nginx / `next.config.js` redirect snippets for 301/410 recommendations.
    - **The 410 Prune Protocol** in the rewrite workflow: every legacy URL gets an explicit 301 (preserve equity) or 410 (prune) recommendation. Silent leave-as-is is no longer acceptable.
    
    ### Changed
    - `dataforseo.py`: `_extract_serp` now passes through the `highlighted` field on every organic result (was being dropped). Required for Meta Entity Isolation.
    - `research.py`: research output now surfaces `primary_intent`, `secondary_intent`, `meta_entities`, and `target_ngrams` at top level (not buried in `analysis`) for direct brief consumption.
    - README.md "What It Actually Does" block expanded from 13 to 14 steps reflecting dual-intent mapping (step 5), n-gram seeding (step 8), and 301/410 governance (step 12).
    - HARD RULES rewritten in SKILL.md: replaced the negative "never use codename X" rule with positive naming guidance ("framework is seo-agi / seobuild-onpage; no prior internal codenames in any output").
    
    ### Tests
    - Added `tests/test_research_v171.py` with 13 new tests covering meta-entity extraction (highlighted field + inline-tag fallback + dedup), n-gram extraction (stopword filtering, top-N limiting, empty-input safety), tokenizer behavior, and secondary-intent funnel + override logic.
    
    ## [1.7.0] - 2026-04-30
    
    ### Added
    - **Tributary Trust Protocol** (Section 11A): off-page architecture for AEO entity validation. Defines Tier 1 owned assets (Google Sites, Medium, Subreddits, Google Sheets, LinkedIn) as tributaries that feed entity signal to the money page. Includes companion-content rules, network topology, derivation matrix, and sequencing requirements.
    - **Core Belief #7**: AEO Entity Validation via Owned Tier 1 Assets. Knowledge Graph inclusion and AI Overview impression share are now primary success signals, gated by off-page corroboration.
    - **`scripts/tributary_gen.py`**: CLI tool that reads a money page, extracts its 500-token chunks + entities + `{{VERIFY}}` tags, and outputs derived companion briefs to `~/Documents/SEO-AGI/tributaries/<slug>/` with a manifest mapping each draft to its host platform.
    - **Execution Protocol step 11**: tributary deployment is now mandatory for commercial-intent and local pages. All quality gates (Reddit Test, Information Gain, Prove-It, `{{VERIFY}}` resolution, Section 9 banned patterns, Entity Consensus) apply equally to off-page content -- thin tributaries net-harm the money page's entity signal.
    
    ### Changed
    - CLAUDE.md directory structure now lists `scripts/tributary_gen.py`
    - CLAUDE.md framework features updated with Tributary Trust capability
    
    ## [1.6.1] - 2026-04-28
    
    ### Fixed
    - **Heading extraction returned empty for every competitor page.** DataForSEO's `on_page/content_parsing/live` endpoint returns headings inside `main_topic[]` and `secondary_topic[]` arrays (each with `h_title` and `level`), not as flat `h1`/`h2`/`h3` arrays. The old `_extract_headings` looked for keys that don't exist, so `Avg H2s: 0, Avg H3s: 0` for every research run regardless of competitor depth. Now correctly walks the topic tree.
    - **Word count returned 0 for every competitor.** `plain_text_word_count` is not a field DataForSEO returns. Now computes from `page_as_markdown` (preferred) with a fallback walking `primary_content[].text`.
    - **Title extraction returned empty.** `header.title` doesn't exist; replaced with markdown H1 detection plus a `main_topic[0].h_title` fallback.
    - Added regression tests covering the real API response shape so this can't silently break again.
    
    ## [1.6.0] - 2026-04-15
    
    ### Added
    - **Ideal Customer Persona (ICP)**: Page brief template now requires a defined ICP with demographics, psychographics, and specific pain points. Content maps to the actual reader, not a generic audience.
    - **Deep Entity History & Identity Tags**: Founding dates, generational ownership, and identity attributes (women-owned, veteran-owned) are now explicit entity signals in Section 4 SEAT Signals.
    - **The Self-Placement Rule**: Listicle guidance now explicitly allows ranking the client #1, provided the entry is objective with a specific use-case and honest tradeoffs.
    - **Keyword Cannibalization Governance**: Section 9 "Never Do" list now prohibits creating pages that compete with existing URLs for the same intent. Sales-focused duplicates get tagged with `noindex` recommendation.
    
    ### Changed
    - Quality checklist expanded from 38 to 41 items (ICP alignment, entity history, cannibalization)
    - Minimum passing score raised to 33/41
    - Both brief templates (Page Brief Template + Execution Protocol) updated with ICP field
    
    ## [1.3.0] - 2026-03-25
    
    ### Added
    - **AI Summary Nugget**: Mandatory 200-character fact-dense block at top of every page, designed for LLM scrapers (Perplexity, Gemini, ChatGPT) to cite as a consensus source
    - **Original Research Block**: Every page must include a data experiment or first-hand observation section to satisfy Google's Experience (E-E-A-T) signal
    - **Map Traffic Shifting**: Local SEO instruction to link from high-traffic informational pages to map embeds, shifting user interaction signals toward local intent
    - **Spam Resilience Logic**: Quality checklist now prioritizes technical relevance density over "human tone" -- factually perfect content is not downgraded for sounding clinical
    - **Recursive Fact-Checking**: New execution step validates every claim against 2+ high-ranking sources for Entity Consensus before delivery
    
    ### Changed
    - Quality checklist expanded from 24 to 28 items
    - Minimum passing score raised to 22/28
    - Execution protocol now has 11 steps (was 10)
    
    ## [1.2.0] - 2026-03-25
    
    ### Added
    - Anti-spam ranking signals: single H1 rule, no EMQ in meta descriptions, no keyword-stuffed alt text, no duplicate content, internal linking requirements
    - EMQ allowed in title and URL, banned in H2/H3/H4 subheadings
    - Interactive elements section (cost calculators, widgets) to defend against AI Overview traffic loss
    - Broken backlink monitoring guidance
    - "Boat anchor" page culling (410 status for unindexable cruft)
    
    ### Changed
    - Quality checklist expanded from 20 to 24 items (added H1, meta desc, heading, alt text checks)
    
    ## [1.1.0] - 2026-03-24
    
    ### Added
    - Hard rule: framework is named seo-agi only; prior internal codenames must not appear in output
    - Mandatory printed scorecard at end of every page output (no exceptions)
    - FAQ/PAA section required (3+ questions, FAQPage schema)
    - JSON-LD schema block required per page type
    - Hub/spoke internal links required in every output
    - RAG Targeting section (write for AI retrieval, not keyword volume)
    - Topical Circle Audit (stay inside core service topic, noindex strays)
    - Off-Page Sequencing (establish external brand footprint before on-page)
    - Reddit Subdomain Indexing (subdomains over standard posts for AI retrieval)
    - Ask Maps / Conversational GBP Optimization
    
    ### Changed
    - Quality checklist expanded from base to 20 items
    - Scorecard enforcement language strengthened ("INCOMPLETE without this table")
    
    ## [1.0.0] - 2026-03-23
    
    ### Added
    - Initial release: GEO framework skill for Claude Code, OpenClaw, and Codex
    - 500-token chunk architecture for Google AI retrieval
    - SEAT signals (Semantic + E-E-A-T + Entity/Knowledge Graph)
    - Google AI Search 7 ranking signals (Gecko, Jetstream, BM25, PCTR, Freshness, Boost/Bury)
    - Reddit Test, Prove-It Details, Not For You, Information Gain quality gates
    - Verification tagging system (VERIFY, RESEARCH NEEDED, SOURCE NEEDED)
    - DataForSEO integration with graceful no-creds fallback
    - MCP tool integration (Ahrefs, SEMRush)
    - Google Search Console pull scripts
    - Skill root discovery loop (works across Claude Code, OpenClaw, Codex, Gemini)
    - Reference files: page templates, schema patterns, quality checklist
    - Mock mode for testing without API keys
    
  • CLAUDE.md9.1 KB9328f3cd533fupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • CONNECTOR.md11 KB8d896ad6b2b2upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • LICENSE1.0 KBec277f227970upstream ↗
    MIT License
    
    Copyright (c) 2026 Greg Bessoni
    
    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:
    
    The above copyright notice and this permission notice shall be included in all
    copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    SOFTWARE.
    
  • requirements.txt115 Beb7795c58381upstream ↗
    requests>=2.28.0
    
    # Optional: Google Search Console support
    # google-auth>=2.0.0
    # google-api-python-client>=2.0.0
    
  • SPEC.md9.9 KB29c827d0f5c5upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • tests/test_dataforseo.py10 KB5b9cdb95a9ecupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • tests/test_dataforseo_nullsafe.py3.9 KBd27b8cc78e1cupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • tests/test_env.py1.4 KBe4cea8e2e555upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • tests/test_gsc_ghost_paths.py4.1 KB425c8861d481upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • tests/test_massive.py3.4 KB2a974118733dupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • tests/test_research_v171.py8.5 KBc718b43d9910upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • tests/test_research_v191.py8.8 KB26dbbbc24270upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • tests/test_research_v200.py5.4 KB839d287ebba1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • tests/test_research_v220.py1.9 KBf505aa2e15d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • tests/test_serp_analyze.py4.0 KBa02a6157ca0cupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/gbessoni-seobuild-onpage.md

// REPO STATS

266 stars
1 open issues
Last commit: 3d ago