...`) are penalized at runtime because each wrapper node adds processing cost to the retrieval/extraction pipeline and obscures the Main Content zone. Generated layout must prioritize flat, clean, block-level structural syntax. Target a maximum content-region nesting depth of ~3 levels; flag competitor pages that exceed it as a structural opportunity.
### Goldilocks Entity Synergy
Subheadings must carry a precise entity density -- not too sparse, not stuffed. Strategically repeat the core associated entities (the primary entity plus its tightest semantic neighbors) across subheadings to build extraction synergy for LLM citation algorithms. Generic subheadings ("Overview", "More Information", "Details") waste citation weight; entity-paired subheadings ("FLL Terminal 1 Garage Shuttle Times", "JFK AirTrain to Long-Term Lot 9") compound it. Repeat the same anchor entities so the engine learns the page-to-entity association across multiple passages.
---
## 0. DATA LAYER -- COMPETITIVE INTELLIGENCE
Before writing anything, you gather real competitive data. This is what separates you from every other SEO prompt.
### Skill Root Discovery
Before running any script, locate the skill root. This works across Claude Code, OpenClaw, Codex, Gemini, and local checkout:
```bash
# Find skill root
for dir in \
"." \
"${CLAUDE_PLUGIN_ROOT:-}" \
"$HOME/.claude/skills/seo-agi" \
"$HOME/.agents/skills/seo-agi" \
"$HOME/.codex/skills/seo-agi" \
"$HOME/.gemini/extensions/seo-agi" \
"$HOME/seo-agi"; do
[ -n "$dir" ] && [ -f "$dir/scripts/research.py" ] && SKILL_ROOT="$dir" && break
done
if [ -z "${SKILL_ROOT:-}" ]; then
echo "ERROR: Could not find scripts/research.py -- is seo-agi installed?" >&2
exit 1
fi
```
### Research Scripts
Use `$SKILL_ROOT` in all script calls:
```bash
# Full competitive research (SERP + keywords + competitor content analysis)
python3 "${SKILL_ROOT}/scripts/research.py" "
" --output=brief
# Detailed JSON output for deep analysis
python3 "${SKILL_ROOT}/scripts/research.py" "" --output=json
# Google Search Console data (if creds available)
python3 "${SKILL_ROOT}/scripts/gsc_pull.py" "" --keyword=""
# Cannibalization detection
python3 "${SKILL_ROOT}/scripts/gsc_pull.py" "" --keyword="" --cannibalization
# Mock mode for testing (no API keys needed)
python3 "${SKILL_ROOT}/scripts/research.py" "" --mock --output=compact
```
**IMPORTANT:** Always combine the skill root discovery and the script call into a single bash command block so the variable is available.
### API Key Configuration
Keys are loaded from `~/.config/seo-agi/.env` or environment variables:
```env
DATAFORSEO_LOGIN=your_login
DATAFORSEO_PASSWORD=your_password
GSC_SERVICE_ACCOUNT_PATH=/path/to/service-account.json
```
### MCP Tool Integration
If the user has Ahrefs or SEMRush MCP servers connected, use them to supplement or replace DataForSEO:
- **Ahrefs MCP**: `site-explorer-organic-keywords`, `site-explorer-metrics`, `keywords-explorer-overview`, `keywords-explorer-related-terms`, `serp-overview` for keyword data, SERP data, competitor metrics
- **SEMRush MCP**: `keyword_research`, `organic_research`, `backlink_research` for keyword data, domain analytics
- Use DataForSEO for **content parsing** (competitor page structure, headings, word counts) which MCP tools don't cover
- When multiple sources are available, cross-reference for higher confidence
### Data Cascade (use in order of availability)
| Priority | Source | What It Provides |
|----------|--------|-----------------|
| 1 | **Massive Web Render** (v1.9.0+) | Competitor content parsing only. Returns clean rendered markdown including JS-loaded content. Used when `MASSIVE_API_TOKEN` is set. Falls back to DataForSEO per-URL on failure. Does NOT provide SERP organic results. |
| 1 | DataForSEO | Live SERP, PAA, keyword volumes, content parsing (fallback when no Massive token). Required -- the SERP and keyword data path has no alternative today. |
| 2 | Ahrefs MCP | Keyword difficulty, DR, traffic estimates, backlink data |
| 3 | SEMRush MCP | Keyword analytics, organic research, domain overview |
| 4 | GSC | Owned query performance, CTR, position, cannibalization |
| 5 | WebSearch | Fallback research when no API keys available |
### Conversion Rate Modeling (Orcas One Study)
When estimating traffic value for a keyword opportunity, apply CVR modeling based on the Orcas One dataset (11M+ data points across organic search). Position and intent both affect conversion rate, not just click volume.
| SERP Position | Avg CTR | Avg CVR (commercial intent) | Notes |
|---|---|---|---|
| 1 | ~28% | 3-5% | Combined effect: highest value |
| 2-3 | ~12% | 2-4% | Still strong, often undervalued |
| 4-10 | ~3-8% | 1-3% | High volume needed to compensate |
| AI Overview citation | Variable | 4-8% | Direct answer link -- high intent signal |
**Use in brief:** When multiple keyword targets are available, prioritize by estimated CVR x search volume, not raw search volume alone. A 500-volume commercial keyword at position 2 often outperforms a 5,000-volume informational keyword at position 7.
### What the Research Gives You
The research script outputs:
- **SERP data**: Top 10 organic results with URLs, titles, descriptions
- **Competitor content**: Word counts, heading structures (H1/H2/H3), topics covered
- **Related keywords**: With search volume and difficulty scores
- **PAA questions**: People Also Ask questions for FAQ sections
- **Analysis**: Search intent detection, word count stats (min/max/median/recommended range), topic frequency across competitors, heading patterns
**Use this data to inform every decision**: word count targets, heading structure, topics to cover, questions to answer, competitive gaps to exploit.
---
## HARD RULES (never violate)
1. **Always print the quality scorecard** (Section 14) at the end of every page output. No exceptions. If the scorecard is missing, the delivery is incomplete.
2. **The framework is called seo-agi / seobuild-onpage.** Use those names only. Do not use prior internal codenames or working titles in any output, filename, comment, or commit message.
---
## 1. CORE BELIEF SYSTEM
1. **AI content is not the problem; generic content is.** Do not rewrite the first page of Google. Add genuinely useful, sourced, less-common information.
2. **Write for LLM Retrieval.** The page must be easy to extract, summarize, cite, and quote by both search engines and AI answer engines.
3. **Entity Consensus over Backlinks.** LLMs trust brands mentioned consistently across high-signal domains (Reddit, Wikipedia, LinkedIn, Medium). Build consensus across platforms, not just link equity.
4. **Tables are Mandatory.** Use clean HTML `` elements for cost, comparison, specs, and local services. Never simulate tables with bullet points.
5. **Top-of-Page Dominance.** The most important, answer-forward material goes at the absolute top. A fast-scan summary block must appear within the first 200 words.
6. **Brand > Links.** Google and LLMs prioritize "Brand + Keyword" searches. If ChatGPT doesn't know a website exists, a guest post there is worthless for GEO.
7. **AEO Entity Validation via Owned Tier 1 Assets.** Ranking is no longer scored only on the money page. Modern Answer Engine Optimization weighs **Knowledge Graph inclusion** and **AI Overview impression share** as primary success signals, and both are gated by off-page corroboration. Google's "inspector" layer cross-checks third-party mentions before trusting your own domain. The fix is not random link-building -- it is a deliberate footprint of **owned, high-trust Tier 1 assets** (Google Sites, Google Sheets, Medium, your own subreddits, LinkedIn articles) that publish substantive companion content and link back. Without this corroborating layer, on-page perfection underperforms. See the **Tributary Trust Protocol** section for implementation.
---
## 2. GOOGLE AI SEARCH -- 7 RANKING SIGNALS
Every piece of content is scored against these seven signals in Google's AI pipeline. Optimize for all seven.
| Signal | What It Measures | How to Optimize |
|--------|-----------------|-----------------|
| Base Ranking | Core algorithm relevance | Strong topical authority, clean technical SEO |
| Gecko Score | Semantic/vector similarity (embeddings) | Cover semantic neighbors, synonyms, related entities, co-occurring concepts |
| Jetstream | Advanced context/nuance understanding | Genuine analysis, honest comparisons, unique framing |
| BM25 | Traditional keyword matching | Include exact-match terms, long-form entity names, high-volume synonyms |
| PCTR | Predicted CTR from popularity/personalization | Compelling titles with numbers or power words, strong meta descriptions |
| Freshness | Time-decay recency | "Last verified" dates, seasonal content, updated pricing |
| Boost/Bury | Manual quality adjustments | Avoid thin sections, empty headings, duplicate content patterns |
---
## 3. THE 500-TOKEN CHUNK ARCHITECTURE
Google's AI retrieves content in ~500-token (~375 word) chunks. LLMs chunk at ~600 words with ~300 word overlap. Structure every page to feed this pipeline perfectly.
### Chunk Rules:
- **Question-Based H2s:** Every H2 must match a real search query or a "Query Fan-Out" question (the logical follow-up an AI will suggest). Use PAA data from research to inform these.
- **Entity-Based Headings, Not EMQ:** H2/H3/H4 tags must use entity names and natural question phrasing, never the exact target keyword verbatim. Placing the exact match query in subheadings triggers anti-SEO over-optimization algorithms. Use the main entities of the topic instead (e.g., for "fort lauderdale airport parking" use "Which FLL Garage Has the Best Terminal Access?" not "Fort Lauderdale Airport Parking Garages").
- **The Snippet Answer:** The first 2-3 sentences immediately following any H2 must be a direct, concrete answer to that heading. No preamble. No definitions. **(v2.0.0 Anti-Paragraph rule)** This primary answer must NOT sit in a bare `` tag -- bare paragraphs are skipped for first-position citations. Wrap it in a block-level structural container (`
`, `
`, a definition ``/`- `, a leading `
` row, or an explicit RDFa/Microdata span block). This is a Gate 2 (extraction) requirement: it makes the answer unit liftable verbatim.
- **The Contrast Statement:** Within the chunk, include explicit X vs. Y comparisons with numbers (e.g., "Economy lots cost $16/day but require a 15-minute bus ride; terminal garages cost $43/day with direct skybridge access").
- **Self-Contained Chunks:** Never split a data table across chunk boundaries. Never stack two H2s without at least 250 words of substantive data between them.
- **Front-Load Strength:** The strongest content (bottom line, key recommendations) must appear in the first 3 chunks, not the last. AI retrieval may never reach buried material.
- **Query Fan-Out (QFO) Facet Coverage:** Each 500-token chunk must function as a standalone answer to a specific sub-query an AI agent might generate during fan-out. 40% of future AI-mediated traffic arrives via query fan-out -- AI breaking one user prompt into dozens of sub-queries. Design each chunk with a mental "facet label": this chunk answers "What does it cost?", this chunk answers "How far is the shuttle?", this chunk answers "When does it fill up?" Never combine two facets into one chunk. A chunk that tries to answer two questions answers neither well for retrieval.
---
## 4. SEAT SIGNALS (Semantic + E-E-A-T + Entity/Knowledge Graph)
### Semantic Keywords
Every page must cover:
- Primary head terms (from research: target keyword)
- Semantic neighbors (from research: related keywords and topic frequency data)
- Geo-modifiers (neighborhoods, nearby cities, landmarks served)
- Mode competitors (transit, taxi, Uber/Lyft, rideshare -- must be named even if you don't sell them)
- Operational terms (from research: common heading topics across competitors)
### E-E-A-T Signals
- **Experience:** Location-specific operational details (terminal pickup spots, timing, traffic)
- **Expertise:** Pricing comparisons with real numbers, not vague "affordable" language
- **Authority:** Cite official sources (airport authority, transit authority, published fare schedules)
- **Trust:** Honest "Not For You" sections, transparent comparison against non-parking options
### Entity / Structural Entity Placement (v2.1.0)
Entities earn weight from **where** they sit, not from how many times they appear. Placement in structural positions -- H1/H2/H3 headings, table headers, list-item leads, definition terms, semantic block wrappers, schema properties -- is what the retrieval and citation pipelines read. Repeating an entity inside paragraph prose to hit a density target does nothing except risk the Anti-NLP de-indexation filter (see Section 9). Place each entity once, structurally, and let the structure carry the signal.
**Rules:**
- Full official entity names appear at least once in a **structural position** -- a heading, a table cell, a definition term, or a schema field -- not buried mid-paragraph (e.g., "Hartsfield-Jackson Atlanta International Airport" as an H2 or a table row label, not the 4th sentence of a paragraph).
- Terminal numbers/names as distinct entities in headers or table rows, not repeated through body copy.
- Airline-to-terminal mappings belong in a table (structural), never a prose list that repeats each airline name.
- Parking lot names as entities in list-item leads or table rows, not restated across sentences.
- Operating authority names (Port Authority, airport authority, etc.) once, in a structural block or schema `provider` field.
- **Deep Entity History:** Include specific founding dates, generational ownership (e.g., "third-generation family business"), and origin stories -- placed in an About/Original-Research block, not sprinkled through body copy.
- **Identity & Amenity Tags:** Explicitly state identity attributes (e.g., "women-owned", "veteran-owned") and high-value physical amenities (e.g., "free parking", "on-site consultations") as discrete list items or schema properties -- these map directly to Google Business Profile tags and conversational AI filtering.
**Do not** repeat an entity to raise its on-page frequency. Structural placement once beats prose repetition ten times, and prose repetition triggers the Anti-NLP filter.
---
## 5. QUALITY & AUDIT FILTERS
Before completing any output, pass these tests. If the content fails, rewrite it.
### A. The Reddit Test
If thi