# seobuild-onpage

Adopt this skill: https://proskills.md/skills/other/gbessoni-seobuild-onpage

Page: https://proskills.md/skills/other/gbessoni-seobuild-onpage
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 111579
sha: 0c19c772b023db293c00caa5d41b71fbfddaa954
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/SKILL.md
truncated: true

```text
---
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
```

## File: README.md
size: 39742
sha: 1fd62629e9e783b9169aab66ec6e01f91e7c901f
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/README.md

````text
# seobuild-onpage v2.6.0

### One command. Competitive data in. Ranking pages out.

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

Not on Claude Code? See [Install + Setup](#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](https://github.com/gbessoni/seobuild-onpage/issues/2) 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 
````

## File: scripts/gsc_pull.py
size: 10618
sha: a1bb7d9fce4d809c35cd5306b5576d7d934599b2
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/scripts/gsc_pull.py

```text
#!/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()
```

## File: scripts/lib/__init__.py
size: 26
sha: 333f3480bfd128b445c426ea2b98cc7757bff86e
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/scripts/lib/__init__.py

```text
# seo-agi scripts library
```

## File: scripts/lib/dataforseo.py
size: 11869
sha: 1260c8b3f6e1d3d121d7dfb4038f1998fe7f1a98
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/scripts/lib/dataforseo.py

```text
"""
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
```

## File: scripts/lib/env.py
size: 4736
sha: 2e9c41e81302cf40700399aa715451bd72e93c92
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/scripts/lib/env.py

```text
"""
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"
```

## File: scripts/lib/gsc_client.py
size: 5514
sha: 9b6b330e1fdbe886121d8164b5ec4afa36e104e3
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/scripts/lib/gsc_client.py

```text
"""
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,
        )
```

## File: scripts/lib/massive.py
size: 4918
sha: 36fc1199ef6f2161e09913bb6bf8cb3158ee4e7d
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/scripts/lib/massive.py

```text
"""
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,
        }
```

## File: scripts/lib/serp_analyze.py
size: 7056
sha: 2d2e00f34be919b4ea1b5f05e7f1a962fad8c2e2
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/scripts/lib/serp_analyze.py

```text
"""
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
        ),
    }
```

## File: scripts/research.py
size: 39232
sha: d3e4030c7b7c673da7786d4aa892a26749d40758
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/scripts/research.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/scripts/research.py

## File: scripts/setup.py
size: 5390
sha: 47c86345079de4950245ba3d2ea035ddc629d1a5
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/scripts/setup.py

```text
#!/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()
```

## File: scripts/tributary_gen.py
size: 12757
sha: b3d09bae58ff59418f07f875564dbd58f4baf723
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/scripts/tributary_gen.py

```text
#!/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())
```

## File: references/page-templates.md
size: 7815
sha: 9e1f0cec9ee6b336be7f6e0448720560aceb525c
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/references/page-templates.md

````text
# 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.
````

## File: references/quality-checklist.md
size: 20870
sha: 10b09e690f3019d5a827412dcc35291610600e3a
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/references/quality-checklist.md

```text
# 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.
```

## File: references/schema-patterns.md
size: 4430
sha: 737b82f88c6229c278e5b9ba3095336f0eaa2249
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/references/schema-patterns.md

````text
# 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.
````

## File: .claude-plugin/marketplace.json
size: 790
sha: 663804526718ea8751a83c5203c664e63200e803
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/.claude-plugin/marketplace.json

```text
{
  "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"
    }
  ]
}
```

## File: .claude-plugin/plugin.json
size: 732
sha: 9e9fd72be400c2d2962dfdbc10035d1f913cc277
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/.claude-plugin/plugin.json

```text
{
  "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"
  ]
}
```

## File: .env.example
size: 1155
sha: 67888554e4e4dd068648b5b628b9cc6a910a2236
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/.env.example

```text
# 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=
```

## File: .gitignore
size: 59
sha: a8beb91f315fcca18c6417fa9c099d199dd1597f
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/.gitignore

```text
__pycache__/
*.pyc
.env
*.egg-info/
dist/
build/
.DS_Store
```

## File: CHANGELOG.md
size: 29999
sha: b585a5d08e48999dfac9813e295a36fab0239e18
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/CHANGELOG.md

```text
# 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
```

## File: CLAUDE.md
size: 9322
sha: 9328f3cd533f7e09bf9499bbe05e7c58f9823240
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/CLAUDE.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/CLAUDE.md

## File: CONNECTOR.md
size: 10822
sha: 8d896ad6b2b263bf78856c3db6270064598c755b
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/CONNECTOR.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/CONNECTOR.md

## File: LICENSE
size: 1069
sha: ec277f227970bbb972768657cb8e211c913d0f6a
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/LICENSE

```text
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.
```

## File: requirements.txt
size: 115
sha: eb7795c583810ba2199a2faeb4ffc9ec9d1d3539
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/requirements.txt

```text
requests>=2.28.0

# Optional: Google Search Console support
# google-auth>=2.0.0
# google-api-python-client>=2.0.0
```

## File: SPEC.md
size: 10169
sha: 29c827d0f5c5ac01fa8be8c6b390966e9a1408ca
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/SPEC.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/SPEC.md

## File: tests/test_dataforseo.py
size: 10253
sha: 5b9cdb95a9ec0fbe5a3e3d785882b4f3d6b83b12
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_dataforseo.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_dataforseo.py

## File: tests/test_dataforseo_nullsafe.py
size: 3982
sha: d27b8cc78e1cbcf0082e1ca77b64ede94b50ea81
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_dataforseo_nullsafe.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_dataforseo_nullsafe.py

## File: tests/test_env.py
size: 1450
sha: e4cea8e2e5556dbec34b6fcf581649aea189093f
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_env.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_env.py

## File: tests/test_gsc_ghost_paths.py
size: 4183
sha: 425c8861d481943f8f1dc895484468ff7e9f9dc8
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_gsc_ghost_paths.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_gsc_ghost_paths.py

## File: tests/test_massive.py
size: 3527
sha: 2a974118733dc731c118b458e6f3c648a60947ab
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_massive.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_massive.py

## File: tests/test_research_v171.py
size: 8655
sha: c718b43d991092eda4bb15a68349f36ee3bf3329
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_research_v171.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_research_v171.py

## File: tests/test_research_v191.py
size: 8963
sha: 26dbbbc24270c3d124799c28837e05806ef17ce7
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_research_v191.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_research_v191.py

## File: tests/test_research_v200.py
size: 5555
sha: 839d287ebba11fc9c3ee3ccb46ea5f5a3fd56bb0
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_research_v200.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_research_v200.py

## File: tests/test_research_v220.py
size: 1919
sha: f505aa2e15d4246ba429b3382e6f960b1360d898
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_research_v220.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_research_v220.py

## File: tests/test_serp_analyze.py
size: 4124
sha: a02a6157ca0c2c0a628742b1cf5e81c67e222662
upstream: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_serp_analyze.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/gbessoni/seobuild-onpage/blob/HEAD/tests/test_serp_analyze.py
