# Branded SEO Page Builder

Generate an on-brand, SEO-optimized HTML page from a domain using Context.dev brand, content, and styleguide data.

- Install: `npx shadcn@latest add @evex/branded-seo-page-builder`
- Category: marketing
- Author: [TommyBez](https://www.evex.sh/authors/TommyBez)
- Updated: 2026-07-04
- Dependencies: eve@^0.18.2
- Web page: https://www.evex.sh/agents/branded-seo-page-builder
- This document: https://www.evex.sh/agents/branded-seo-page-builder.md

## Overview

Branded SEO Page Builder is an eve agent that turns a bare domain into one complete, SEO-optimized HTML page. You interact with it in chat: ask for a page from a domain such as linear.app, or point it at a specific source URL and a target topic, and it returns a full static document with metadata, Open Graph and Twitter card tags, semantic sections, and JSON-LD structured data.

What makes it useful is grounding. The agent connects to Context.dev's hosted MCP server at context-dev.stlmcp.com to resolve real brand data for the domain: company name, description, colors, logos, industry labels, homepage content as markdown, and optional styleguide signals like typography and spacing. Every user-facing claim in the generated page comes from that data or your explicit request, never invented statistics, testimonials, or pricing.

Two vendored skills shape the output. The seo-audit skill enforces on-page fundamentals such as one h1, canonical tags, descriptive alt text, and intent-matched schema types, while the ai-seo skill structures copy into extractable answer blocks and FAQ sections so answer engines like ChatGPT, Perplexity, and Google AI Overviews can cite the page, not only rank it.

## How it works

1. You ask for a page in chat, for example 'Create an SEO-optimized landing page for linear.app'; if no domain is given, the agent stops and asks for one before doing any generation work.
2. It loads the bundled seo-audit skill to plan page structure, metadata, headings, canonical tags, image alt text, and schema, then loads the ai-seo skill before writing body copy so sections stay extractable and answer-oriented.
3. Through the context-dev MCP connection it discovers Context.dev tools via connection_search, consults search_docs for exact SDK method names, and calls execute to fetch brand data, page markdown, and styleguide details for the domain.
4. It infers the most useful page intent from the request and the retrieved data, choosing between homepage, landing, feature, comparison, local, or product page, and only asks a follow-up when the data cannot support a sensible choice.
5. It generates one complete HTML document with inline CSS reflecting the brand's colors and typography, a single h1, Open Graph and Twitter card tags, an FAQ section when it fits, and JSON-LD using Organization, WebPage, FAQPage, Product, or Service.
6. It returns the document in a single fenced html block followed by SEO notes covering search intent, primary keyword, secondary topics, schema types, and Context.dev source URLs, plus an assumptions list whenever copy relied on inference; two bundled evals verify the missing-domain guard and this page-structure contract.

## Use cases

### Landing page from a domain in minutes

Give the agent a prospect's or your own domain and get a launch-ready static landing page whose copy, colors, and typography match the live brand, complete with metadata and structured data for immediate deployment.

### Programmatic SEO page drafts

Generate grounded first drafts for feature, comparison, or product pages by pointing the agent at a specific source URL and target keyword, such as building a product page targeting AI support automation.

### AI answer engine visibility

Produce pages structured for citation by ChatGPT, Perplexity, and Google AI Overviews, with extractable answer blocks, FAQ sections, and FAQPage schema, while staying people-first to avoid scaled content abuse penalties.

### On-brand pages for agency clients

Agencies can prototype an SEO page for any client domain without collecting brand assets manually; Context.dev supplies logos, colors, industry labels, and homepage copy so the draft looks like the client made it.

## Requirements

- `CONTEXT_DEV_API_KEY`: Context.dev API key used to authenticate the hosted MCP server at context-dev.stlmcp.com via the x-context-dev-api-key header. Create one in your Context.dev account; keys look like ctxt_secret_. The agent refuses to run brand lookups without it.
- `CONTEXT_API_KEY`: Optional fallback variable read when CONTEXT_DEV_API_KEY is unset, for projects that already use this name. CONTEXT_DEV_API_KEY is the documented standard; set only one of the two.
- `eve@^0.18.2`: The eve framework runtime that hosts the agent, its MCP client connection, skills, and evals. Installed as the registry item's dependency; the agent package requires Node 24 or newer.

## FAQ

### How do I install and run it?

Run npx shadcn@latest add @evex/branded-seo-page-builder in your eve app, copy .env.example and set CONTEXT_DEV_API_KEY, then start with pnpm dev and ask the agent in chat for a page from any domain.

### Which model does the agent use?

It is configured with zai/glm-5.2-fast in agent/agent.ts. You can swap the model by editing the defineAgent call; the instructions, skills, and Context.dev connection work independently of the model choice.

### What output do I actually get?

One complete HTML document in a single fenced html block with inline CSS and no JavaScript unless requested, followed by SEO notes listing search intent, primary keyword, secondary topics, schema types, and Context.dev source URLs, plus assumptions when copy was inferred.

### What happens if Context.dev has little data for a domain, or the API fails?

The agent will not fabricate brand facts. On a missing or invalid key, a 401, or a 429 rate limit it stops and reports the failure; with thin brand data it asks for more source copy or a specific page URL instead of inventing claims.

### Can I customize the visual style or page type?

Yes. By default the agent applies Context.dev styleguide data for colors, typography, spacing, and shadows. You can pass a specific source page URL, request a particular intent like a comparison or product page, or ask it to skip styleguide data entirely.

## Files installed

- `agent/agent.ts`
- `agent/connections/context-dev.ts`
- `agent/instructions.md`
- `agent/skills/ai-seo/references/content-patterns.md`
- `agent/skills/ai-seo/references/content-types.md`
- `agent/skills/ai-seo/references/okf.md`
- `agent/skills/ai-seo/references/platform-ranking-factors.md`
- `agent/skills/ai-seo/SKILL.md`
- `agent/skills/seo-audit/references/ai-writing-detection.md`
- `agent/skills/seo-audit/references/international-seo.md`
- `agent/skills/seo-audit/SKILL.md`
- `evals/evals.config.ts`
- `evals/missing-domain-asks.eval.ts`
- `evals/page-structure-contract.eval.ts`
- `agent/README.md`
- `.env.example`

## File contents

### `agent/agent.ts`

```ts
import { defineAgent } from "eve";

export default defineAgent({
  model: "zai/glm-5.2-fast",
});

```

### `agent/connections/context-dev.ts`

```ts
import { defineMcpClientConnection } from "eve/connections";

export default defineMcpClientConnection({
  url: "https://context-dev.stlmcp.com",
  description:
    "Context.dev hosted MCP for resolving brand data, scraping webpages, crawling sites, and extracting styleguides from domains. Use it to gather the brand, content, and design context needed before generating SEO HTML.",
  headers: {
    "x-context-dev-api-key": readContextDevApiKey,
  },
  tools: {
    allow: ["search_docs", "execute"],
  },
});

function readContextDevApiKey(): string {
  const apiKey =
    process.env.CONTEXT_DEV_API_KEY?.trim() || process.env.CONTEXT_API_KEY?.trim();

  if (!apiKey) {
    throw new Error(
      "Missing CONTEXT_DEV_API_KEY or CONTEXT_API_KEY for Context.dev MCP access.",
    );
  }

  return apiKey;
}

```

### `agent/instructions.md`

```md
# Mission
Build an SEO-optimized, on-brand HTML page from a user-provided domain.

# Workflow
1. If the user has not provided a domain, ask for the domain before doing any
   generation work.
2. Load the `seo-audit` skill before planning page structure, metadata, headings,
   canonical tags, internal-link recommendations, image alt text, and schema.
3. Load the `ai-seo` skill before writing the page body so the content is
   extractable, answer-oriented, and useful for AI search systems without making
   spammy AI-only content.
4. Use the `context-dev` MCP connection through `connection_search` to discover
   the Context.dev tools. Use `search_docs` when you need the exact SDK method or
   parameter names, then use `execute` to gather the source data.
5. Through Context.dev MCP, retrieve at minimum:
   - brand data for the domain, including name, description, colors, logos,
     industry labels, and social/profile fields when available;
   - homepage or provided page markdown;
   - styleguide/design-system data for colors, typography, spacing, shadows, and
     component cues when available.
6. Treat Context.dev brand, content, and styleguide outputs as the source of truth
   for brand name, positioning, industry, colors, typography cues, social proof,
   logos, and factual claims.
7. If the Context.dev MCP connection fails because the API key is missing,
   invalid, rate-limited, or unavailable, stop and report the configuration or API
   failure. Do not fabricate brand facts.
8. Infer the most useful page intent from the user request and Context.dev data:
   homepage, landing page, feature page, comparison page, local page, or product
   page. Ask a follow-up only when the domain data is not enough to choose a
   sensible intent.
9. Produce one complete HTML document, not a framework component. Include inline
   CSS that reflects the Context.dev brand/styleguide output. Keep JavaScript out
   unless the user explicitly asks for it.

# HTML requirements
- Include `<!doctype html>`, `<html lang="...">`, `<head>`, and `<body>`.
- Add a concise `<title>`, meta description, canonical URL, Open Graph tags, and
  Twitter card tags.
- Use one clear `<h1>`, logical heading hierarchy, semantic sections, and
  descriptive link text.
- Include an FAQ or answer-focused section when it fits the page intent.
- Include JSON-LD structured data in `application/ld+json`. Prefer
  `Organization`, `WebPage`, `FAQPage`, `Product`, or `Service` based on the
  Context.dev data and page intent.
- Use only claims grounded in the Context.dev result, the scraped homepage
  markdown, or the user's explicit request. Mark reasonable but unverified
  copywriting assumptions as comments after the HTML, not inside metadata.
- Include accessible alt text for any image/logo URL used from Context.dev.
- Optimize for fast static delivery: no remote scripts, no heavy animation, no
  layout shift from missing dimensions when image dimensions are known.

# Output contract
Return:
1. The complete HTML document in a single fenced `html` block.
2. A short "SEO notes" section with target search intent, primary keyword,
   secondary topics, schema types used, and Context.dev source URLs.
3. A short "Assumptions" section only if any user-facing copy relies on inference
   rather than explicit source data.

# Guardrails
- Do not invent statistics, awards, customer names, pricing, certifications, or
  testimonials.
- Do not expose the Context.dev API key or any environment variables.
- Do not call Context.dev directly from browser-side code in the generated page.
- Do not perform an SEO audit report instead of generating HTML unless the user
  explicitly asks for an audit.

```

### `agent/skills/ai-seo/references/content-patterns.md`

````md
# AEO and GEO Content Patterns

Reusable content block patterns optimized for answer engines and AI citation.

---

## Contents
- Answer Engine Optimization (AEO) Patterns (Definition Block, Step-by-Step Block, Comparison Table Block, Pros and Cons Block, FAQ Block, Listicle Block)
- Generative Engine Optimization (GEO) Patterns (Statistic Citation Block, Expert Quote Block, Authoritative Claim Block, Self-Contained Answer Block, Evidence Sandwich Block)
- Domain-Specific GEO Tactics (Technology Content, Health/Medical Content, Financial Content, Legal Content, Business/Marketing Content)
- Voice Search Optimization (Question Formats for Voice, Voice-Optimized Answer Structure)

## Answer Engine Optimization (AEO) Patterns

These patterns help content appear in featured snippets, AI Overviews, voice search results, and answer boxes.

### Definition Block

Use for "What is [X]?" queries.

```markdown
## What is [Term]?

[Term] is [concise 1-sentence definition]. [Expanded 1-2 sentence explanation with key characteristics]. [Brief context on why it matters or how it's used].
```

**Example:**
```markdown
## What is Answer Engine Optimization?

Answer Engine Optimization (AEO) is the practice of structuring content so AI-powered systems can easily extract and present it as direct answers to user queries. Unlike traditional SEO that focuses on ranking in search results, AEO optimizes for featured snippets, AI Overviews, and voice assistant responses. This approach has become essential as over 60% of Google searches now end without a click.
```

### Step-by-Step Block

Use for "How to [X]" queries. Optimal for list snippets.

```markdown
## How to [Action/Goal]

[1-sentence overview of the process]

1. **[Step Name]**: [Clear action description in 1-2 sentences]
2. **[Step Name]**: [Clear action description in 1-2 sentences]
3. **[Step Name]**: [Clear action description in 1-2 sentences]
4. **[Step Name]**: [Clear action description in 1-2 sentences]
5. **[Step Name]**: [Clear action description in 1-2 sentences]

[Optional: Brief note on expected outcome or time estimate]
```

**Example:**
```markdown
## How to Optimize Content for Featured Snippets

Earning featured snippets requires strategic formatting and direct answers to search queries.

1. **Identify snippet opportunities**: Use tools like Semrush or Ahrefs to find keywords where competitors have snippets you could capture.
2. **Match the snippet format**: Analyze whether the current snippet is a paragraph, list, or table, and format your content accordingly.
3. **Answer the question directly**: Provide a clear, concise answer (40-60 words for paragraph snippets) immediately after the question heading.
4. **Add supporting context**: Expand on your answer with examples, data, and expert insights in the following paragraphs.
5. **Use proper heading structure**: Place your target question as an H2 or H3, with the answer immediately following.

Most featured snippets appear within 2-4 weeks of publishing well-optimized content.
```

### Comparison Table Block

Use for "[X] vs [Y]" queries. Optimal for table snippets.

```markdown
## [Option A] vs [Option B]: [Brief Descriptor]

| Feature | [Option A] | [Option B] |
|---------|------------|------------|
| [Criteria 1] | [Value/Description] | [Value/Description] |
| [Criteria 2] | [Value/Description] | [Value/Description] |
| [Criteria 3] | [Value/Description] | [Value/Description] |
| [Criteria 4] | [Value/Description] | [Value/Description] |
| Best For | [Use case] | [Use case] |

**Bottom line**: [1-2 sentence recommendation based on different needs]
```

### Pros and Cons Block

Use for evaluation queries: "Is [X] worth it?", "Should I [X]?"

```markdown
## Advantages and Disadvantages of [Topic]

[1-sentence overview of the evaluation context]

### Pros

- **[Benefit category]**: [Specific explanation]
- **[Benefit category]**: [Specific explanation]
- **[Benefit category]**: [Specific explanation]

### Cons

- **[Drawback category]**: [Specific explanation]
- **[Drawback category]**: [Specific explanation]
- **[Drawback category]**: [Specific explanation]

**Verdict**: [1-2 sentence balanced conclusion with recommendation]
```

### FAQ Block

Use for topic pages with multiple common questions. Essential for FAQ schema.

```markdown
## Frequently Asked Questions

### [Question phrased exactly as users search]?

[Direct answer in first sentence]. [Supporting context in 2-3 additional sentences].

### [Question phrased exactly as users search]?

[Direct answer in first sentence]. [Supporting context in 2-3 additional sentences].

### [Question phrased exactly as users search]?

[Direct answer in first sentence]. [Supporting context in 2-3 additional sentences].
```

**Tips for FAQ questions:**
- Use natural question phrasing ("How do I..." not "How does one...")
- Include question words: what, how, why, when, where, who, which
- Match "People Also Ask" queries from search results
- Keep answers between 50-100 words

### Listicle Block

Use for "Best [X]", "Top [X]", "[Number] ways to [X]" queries.

```markdown
## [Number] Best [Items] for [Goal/Purpose]

[1-2 sentence intro establishing context and selection criteria]

### 1. [Item Name]

[Why it's included in 2-3 sentences with specific benefits]

### 2. [Item Name]

[Why it's included in 2-3 sentences with specific benefits]

### 3. [Item Name]

[Why it's included in 2-3 sentences with specific benefits]
```

---

## Generative Engine Optimization (GEO) Patterns

These patterns optimize content for citation by AI assistants like ChatGPT, Claude, Perplexity, and Gemini.

### Statistic Citation Block

Statistics increase AI citation rates by 15-30%. Always include sources.

```markdown
[Claim statement]. According to [Source/Organization], [specific statistic with number and timeframe]. [Context for why this matters].
```

**Example:**
```markdown
Mobile optimization is no longer optional for SEO success. According to Google's 2024 Core Web Vitals report, 70% of web traffic now comes from mobile devices, and pages failing mobile usability standards see 24% higher bounce rates. This makes mobile-first indexing a critical ranking factor.
```

### Expert Quote Block

Named expert attribution adds credibility and increases citation likelihood.

```markdown
"[Direct quote from expert]," says [Expert Name], [Title/Role] at [Organization]. [1 sentence of context or interpretation].
```

**Example:**
```markdown
"The shift from keyword-driven search to intent-driven discovery represents the most significant change in SEO since mobile-first indexing," says Rand Fishkin, Co-founder of SparkToro. This perspective highlights why content strategies must evolve beyond traditional keyword optimization.
```

### Authoritative Claim Block

Structure claims for easy AI extraction with clear attribution.

```markdown
[Topic] [verb: is/has/requires/involves] [clear, specific claim]. [Source] [confirms/reports/found] that [supporting evidence]. This [explains/means/suggests] [implication or action].
```

**Example:**
```markdown
E-E-A-T is the cornerstone of Google's content quality evaluation. Google's Search Quality Rater Guidelines confirm that trust is the most critical factor, stating that "untrustworthy pages have low E-E-A-T no matter how experienced, expert, or authoritative they may seem." This means content creators must prioritize transparency and accuracy above all other optimization tactics.
```

### Self-Contained Answer Block

Create quotable, standalone statements that AI can extract directly.

```markdown
**[Topic/Question]**: [Complete, self-contained answer that makes sense without additional context. Include specific details, numbers, or examples in 2-3 sentences.]
```

**Example:**
```markdown
**Ideal blog post length for SEO**: The optimal length for SEO blog posts is 1,500-2,500 words for competitive topics. This range allows comprehensive topic coverage while maintaining reader engagement. HubSpot research shows long-form content earns 77% more backlinks than short articles, directly impacting search rankings.
```

### Evidence Sandwich Block

Structure claims with evidence for maximum credibility.

```markdown
[Opening claim statement].

Evidence supporting this includes:
- [Data point 1 with source]
- [Data point 2 with source]
- [Data point 3 with source]

[Concluding statement connecting evidence to actionable insight].
```

---

## Domain-Specific GEO Tactics

Different content domains benefit from different authority signals.

### Technology Content
- Emphasize technical precision and correct terminology
- Include version numbers and dates for software/tools
- Reference official documentation
- Add code examples where relevant

### Health/Medical Content
- Cite peer-reviewed studies with publication details
- Include expert credentials (MD, RN, etc.)
- Note study limitations and context
- Add "last reviewed" dates

### Financial Content
- Reference regulatory bodies (SEC, FTC, etc.)
- Include specific numbers with timeframes
- Note that information is educational, not advice
- Cite recognized financial institutions

### Legal Content
- Cite specific laws, statutes, and regulations
- Reference jurisdiction clearly
- Include professional disclaimers
- Note when professional consultation is advised

### Business/Marketing Content
- Include case studies with measurable results
- Reference industry research and reports
- Add percentage changes and timeframes
- Quote recognized thought leaders

---

## Voice Search Optimization

Voice queries are conversational and question-based. Optimize for these patterns:

### Question Formats for Voice
- "What is..."
- "How do I..."
- "Where can I find..."
- "Why does..."
- "When should I..."
- "Who is..."

### Voice-Optimized Answer Structure
- Lead with direct answer (under 30 words ideal)
- Use natural, conversational language
- Avoid jargon unless targeting expert audience
- Include local context where relevant
- Structure for single spoken response

````

### `agent/skills/ai-seo/references/content-types.md`

```md
# AI SEO by Content Type

Tactical guidance for optimizing specific content types for AI search citation. These tactics work for non-Google AI engines (ChatGPT, Claude, Perplexity, Copilot) and don't hurt Google AI Overviews / AI Mode.

For the cross-cutting strategy, see [SKILL.md](../SKILL.md).

---

## SaaS Product Pages

**Goal:** Get cited in "What is [category]?" and "Best [category]" queries.

**Optimize:**
- Clear product description in first paragraph (what it does, who it's for)
- Feature comparison tables (you vs. category, not just competitors)
- Specific metrics ("processes 10,000 transactions/sec" not "blazing fast")
- Customer count or social proof with numbers
- Pricing transparency (AI cites pages with visible pricing) — add a `/pricing.md` file so AI agents can parse your plans without rendering your page (see "Machine-Readable Files" in the main skill)
- FAQ section addressing common buyer questions

---

## Blog Content

**Goal:** Get cited as an authoritative source on topics in your space.

**Optimize:**
- One clear target query per post (match heading to query)
- Definition in first paragraph for "What is" queries
- Original data, research, or expert quotes
- "Last updated" date visible
- Author bio with relevant credentials
- Internal links to related product/feature pages

---

## Comparison / Alternative Pages

**Goal:** Get cited in "[X] vs [Y]" and "Best [X] alternatives" queries.

**Optimize:**
- Structured comparison tables (not just prose)
- Fair and balanced (AI penalizes obviously biased comparisons)
- Specific criteria with ratings or scores
- Updated pricing and feature data
- Ground every comparison in current source data and cite each source inline

---

## Documentation / Help Content

**Goal:** Get cited in "How to [X] with [your product]" queries.

**Optimize:**
- Step-by-step format with numbered lists
- Code examples where relevant
- HowTo schema markup
- Screenshots with descriptive alt text
- Clear prerequisites and expected outcomes

---

## Local Business / Ecom (Google emphasis)

Google's AI features pull from product feeds and business profiles for local + ecom queries. Optimize:

- **Merchant Center feeds** kept current with accurate inventory, pricing, attributes
- **Google Business Profile** complete with hours, services, photos, posts, Q&A answered
- **Reviews** — recent + sufficient volume; respond to reviews to signal active management
- **Service area schema** for local services
- **Business Agent** (where available) for conversational customer engagement

```

### `agent/skills/ai-seo/references/okf.md`

````md
# Open Knowledge Format (OKF)

Google's v0.1 markdown spec for representing site content as an agent-readable bundle. Introduced on the [Google Cloud blog](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) on 2026-06-12 and shipped inside Knowledge Catalog.

## What it is

OKF is a directory of cross-linked markdown files. Each file has:

- A YAML frontmatter block (`type` required; `title`, `description`, `resource`, `tags`, `timestamp` recommended)
- A standard Markdown body
- Standard Markdown links to other files in the bundle (which the spec treats as concept relationships)

An optional `index.md` lists the files for progressive disclosure. The bundle can be distributed as a git repo (recommended), a tarball/zip, or a subdirectory of a larger repo.

The [full spec](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/HEAD/okf/SPEC.md) fits on one page. The repo lives under `GoogleCloudPlatform` (the "not an official Google product" disclaimer is Google's standard open-source boilerplate, not a denial — it appears on most of Google's open-source repos including their main AI samples repo).

### A minimal concept file

```markdown
---
type: Article
title: How to Connect the Ahrefs MCP Server to Manus
description: The official MCP servers, why they did not connect, and the fix.
resource: https://yoursite.com/blog/ahrefs-mcp-manus/
tags: [mcp, ahrefs]
---

# How to Connect the Ahrefs MCP Server to Manus

The body of the post, as clean Markdown.
```

Add an `index.md` that lists all files so an agent can see the bundle's shape before opening each file, and that is the entire format.

## Honest framing

**Google built OKF for data teams sharing catalog metadata** — BigQuery tables, API endpoints, metrics, playbooks. Most of the spec's examples are data-team artifacts, not blog posts. Google's blog post framing: "improve data sharing" and "standardized documentation" for collaboration across teams.

Pointing OKF at a marketing site is a **clever repurposing** popularized by [Suganthan Mohanadasan](https://suganthan.com/blog/open-knowledge-format/). It's a legitimate use case for the format but not Google's primary one. Frame it accurately when explaining it to founders or marketing teams.

## What it does for AI search today

As of 2026-06-27, there is no known broad web crawling support for OKF bundles: the spec is still new, no major AI engine has announced public integration, and Knowledge Catalog ingests bundles only for paying enterprise customers' data teams.

Treat OKF as **protocol-layer registration** — the same shape of bet as early `schema.org` adoption was a decade ago. Schema took the better part of ten years to pay off; people who shipped it early are still glad they did.

A secondary benefit that pays off today regardless: **generating the bundle is itself an internal-linking audit**. Suganthan's tool draws every page as a node and every internal link as an edge, so islands and orphans become obvious at a glance.

## Where OKF fits in the agent-readable stack

| Layer | Purpose |
|---|---|
| `sitemap.xml` | Tells a crawler which URLs exist |
| `robots.txt` (with AI bot rules) | Permits or blocks AI crawlers |
| `llms.txt` | Points an agent at the handful of pages you most want read |
| `/pricing.md` | Structured pricing for agent-buyer comparisons |
| **`/okf/` bundle** | Hands over the content itself as cross-linked concepts |
| Schema markup | Per-page structured data (Article, FAQPage, Product, etc.) |

These stack rather than compete. `llms.txt` is a signpost, OKF is the library.

## How to ship one

Three options, ordered by how much effort they take:

### 1. Suganthan's free web tool (recommended for most sites)

[suganthan.com/okf-generator](https://suganthan.com/okf-generator/) — paste a URL or sitemap, crawls up to 100 pages, returns a downloadable bundle. Also draws the resulting page graph so you can spot disconnected pages before publishing.

### 2. WordPress plugin (pending wp.org approval)

Suganthan's plugin (free, GPL, awaiting wp.org approval at time of writing) installs in a minute, serves the bundle at `/okf/`, and rebuilds on every publish or edit so it stays in sync. Direct download link is in [his blog post](https://suganthan.com/blog/open-knowledge-format/). Requires WordPress 6.0+ and PHP 7.4+. Read-only — never edits posts or settings.

### 3. By hand

Only practical for a handful of pages. Each post becomes a markdown file with frontmatter that you cross-link manually. Miserable for a whole site.

## Hosting & discovery

Serve the bundle at `yoursite.com/okf/`, starting with `yoursite.com/okf/index.md`:

- **Static hosts / Cloudflare**: drag and drop
- **WordPress**: Suganthan's plugin handles the serving
- **Static sites with custom paths**: upload the directory to `/okf/`
- **Closed platforms (Wix, Squarespace, most page-builders)**: you usually can't serve files at custom paths — skip OKF entirely

After it's serving, add a line to `llms.txt` pointing to the bundle so agents that read `llms.txt` (today) can discover the bundle (later).

## When to skip

- Site is <10 pages — overhead exceeds payoff
- Site is on a closed platform that won't allow custom paths
- You're not maintaining `llms.txt`, schema markup, or other machine-readable files (OKF compounds with those; alone it does nothing)
- You can't budget the 30 minutes a quarter to refresh the bundle as content changes

## What to watch

OKF is v0.1, weeks old. Worth tracking, not worth obsessing over:

- Whether Google announces OKF support in AI Overviews / Knowledge Graph (currently no signal)
- Whether non-Google engines (ChatGPT, Perplexity, Claude) announce OKF reading
- Whether the spec moves to v1.0 (breaking changes are possible at <1.0)
- Whether Knowledge Catalog adds public ingestion endpoints
- Adoption signals — search GitHub for `okf/index.md` to see who's shipping bundles

````

### `agent/skills/ai-seo/references/platform-ranking-factors.md`

````md
# How Each AI Platform Picks Sources

Each AI search platform has its own search index, ranking logic, and content preferences. This guide covers what matters for getting cited on each one.

Sources cited throughout: Princeton GEO study (KDD 2024), SE Ranking domain authority study, ZipTie content-answer fit analysis.

---

## The Fundamentals

Every AI platform shares three baseline requirements:

1. **Your content must be in their index** — Each platform uses a different search backend (Google, Bing, Brave, or their own). If you're not indexed, you can't be cited.
2. **Your content must be crawlable** — AI bots need access via robots.txt. Block the bot, lose the citation.
3. **Your content must be extractable** — AI systems pull passages, not pages. Clear structure and self-contained paragraphs win.

Beyond these basics, each platform weights different signals. Here's what matters and where.

---

## Google AI Overviews

Google AI Overviews pull from Google's own index and lean heavily on E-E-A-T signals (Experience, Expertise, Authoritativeness, Trustworthiness). They appear in roughly 45% of Google searches.

**What makes Google AI Overviews different:** They already have your traditional SEO signals — backlinks, page authority, topical relevance. The additional AI layer adds a preference for content with cited sources and structured data. Research shows that including authoritative citations in your content correlates with a 132% visibility boost, and writing with an authoritative (not salesy) tone adds another 89%.

**Importantly, AI Overviews don't just recycle the traditional Top 10.** Only about 15% of AI Overview sources overlap with conventional organic results. Pages that wouldn't crack page 1 in traditional search can still get cited if they have strong structured data and clear, extractable answers.

**What to focus on:**
- Schema markup is the single biggest lever — Article, FAQPage, HowTo, and Product schemas give AI Overviews structured context to work with (30-40% visibility boost)
- Build topical authority through content clusters with strong internal linking
- Include named, sourced citations in your content (not just claims)
- Author bios with real credentials matter — E-E-A-T is weighted heavily
- Get into Google's Knowledge Graph where possible (an accurate Wikipedia entry helps)
- Target "how to" and "what is" query patterns — these trigger AI Overviews most often

**Watch for OKF.** In June 2026 Google introduced the [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) — a markdown spec for agent-readable site bundles. There is no confirmed signal that AI Overviews factor it in today, but the spec is published, the GitHub repo lives under `GoogleCloudPlatform`, and it ships inside Knowledge Catalog. For protocol-layer "register early" plays, it has the same shape as early schema.org adoption did a decade ago. See **Machine-Readable Files for AI Agents** in the main `SKILL.md` for how to generate and serve a bundle.

---

## ChatGPT

ChatGPT's web search draws from a Bing-based index. It combines this with its training knowledge to generate answers, then cites the web sources it relied on.

**What makes ChatGPT different:** Domain authority matters more here than on other AI platforms. An SE Ranking analysis of 129,000 domains found that authority and credibility signals account for roughly 40% of what determines citation, with content quality at about 35% and platform trust at 25%. Sites with very high referring domain counts (350K+) average 8.4 citations per response, while sites with slightly lower trust scores (91-96 vs 97-100) drop from 8.4 to 6 citations.

**Freshness is a major differentiator.** Content updated within the last 30 days gets cited about 3.2x more often than older content. ChatGPT clearly favors recent information.

**The most important signal is content-answer fit** — a ZipTie analysis of 400,000 pages found that how well your content's style and structure matches ChatGPT's own response format accounts for about 55% of citation likelihood. This is far more important than domain authority (12%) or on-page structure (14%) alone. Write the way ChatGPT would answer the question, and you're more likely to be the source it cites.

**Where ChatGPT looks beyond your site:** Wikipedia accounts for 7.8% of all ChatGPT citations, Reddit for 1.8%, and Forbes for 1.1%. Brand official sites are cited frequently but third-party mentions carry significant weight.

**What to focus on:**
- Invest in backlinks and domain authority — it's the strongest baseline signal
- Update competitive content at least monthly
- Structure your content the way ChatGPT structures its answers (conversational, direct, well-organized)
- Include verifiable statistics with named sources
- Clean heading hierarchy (H1 > H2 > H3) with descriptive headings

---

## Perplexity

Perplexity always cites its sources with clickable links, making it the most transparent AI search platform. It combines its own index with Google's and runs results through multiple reranking passes — initial relevance retrieval, then traditional ranking factor scoring, then ML-based quality evaluation that can discard entire result sets if they don't meet quality thresholds.

**What makes Perplexity different:** It's the most "research-oriented" AI search engine, and its citation behavior reflects that. Perplexity maintains curated lists of authoritative domains (Amazon, GitHub, major academic sites) that get inherent ranking boosts. It uses a time-decay algorithm that evaluates new content quickly, giving fresh publishers a real shot at citation.

**Perplexity has unique content preferences:**
- **FAQ Schema (JSON-LD)** — Pages with FAQ structured data get cited noticeably more often
- **PDF documents** — Publicly accessible PDFs (whitepapers, research reports) are prioritized. If you have authoritative PDF content gated behind a form, consider making a version public.
- **Publishing velocity** — How frequently you publish matters more than keyword targeting
- **Self-contained paragraphs** — Perplexity prefers atomic, semantically complete paragraphs it can extract cleanly

**What to focus on:**
- Allow PerplexityBot in robots.txt
- Implement FAQPage schema on any page with Q&A content
- Host PDF resources publicly (whitepapers, guides, reports)
- Add Article schema with publication and modification timestamps
- Write in clear, self-contained paragraphs that work as standalone answers
- Build deep topical authority in your specific niche

---

## Microsoft Copilot

Copilot is embedded across Microsoft's ecosystem — Edge, Windows, Microsoft 365, and Bing Search. It relies entirely on Bing's index, so if Bing hasn't indexed your content, Copilot can't cite it.

**What makes Copilot different:** The Microsoft ecosystem connection creates unique optimization opportunities. Mentions and content on LinkedIn and GitHub provide ranking boosts that other platforms don't offer. Copilot also puts more weight on page speed — sub-2-second load times are a clear threshold.

**What to focus on:**
- Submit your site to Bing Webmaster Tools (many sites only submit to Google Search Console)
- Use IndexNow protocol for faster indexing of new and updated content
- Optimize page speed to under 2 seconds
- Write clear entity definitions — when your content defines a term or concept, make the definition explicit and extractable
- Build presence on LinkedIn (publish articles, maintain company page) and GitHub if relevant
- Ensure Bingbot has full crawl access

---

## Claude

Claude uses Brave Search as its search backend when web search is enabled — not Google, not Bing. This is a completely different index, which means your Brave Search visibility directly determines whether Claude can find and cite you.

**What makes Claude different:** Claude is extremely selective about what it cites. While it processes enormous amounts of content, its citation rate is very low — it's looking for the most factually accurate, well-sourced content on a given topic. Data-rich content with specific numbers and clear attribution performs significantly better than general-purpose content.

**What to focus on:**
- Verify your content appears in Brave Search results (search for your brand and key terms at search.brave.com)
- Allow ClaudeBot and anthropic-ai user agents in robots.txt
- Maximize factual density — specific numbers, named sources, dated statistics
- Use clear, extractable structure with descriptive headings
- Cite authoritative sources within your content
- Aim to be the most factually accurate source on your topic — Claude rewards precision

---

## Allowing AI Bots in robots.txt

If your robots.txt blocks an AI bot, that platform can't cite your content. Here are the user agents to allow:

```text
User-agent: GPTBot           # OpenAI — powers ChatGPT search
User-agent: ChatGPT-User     # ChatGPT browsing mode
User-agent: PerplexityBot    # Perplexity AI search
User-agent: ClaudeBot        # Anthropic Claude
User-agent: anthropic-ai     # Anthropic Claude (alternate)
User-agent: Google-Extended   # Google Gemini and AI Overviews
User-agent: Bingbot          # Microsoft Copilot (via Bing)
Allow: /
```

**Training vs. search:** Some AI bots are used for both model training and search citation. If you want to be cited but don't want your content used for training, your options are limited — GPTBot handles both for OpenAI. However, you can safely block **CCBot** (Common Crawl) without affecting any AI search citations, since it's only used for training dataset collection.

---

## Where to Start

If you're optimizing for AI search for the first time, focus your effort where your audience actually is:

**Start with Google AI Overviews** — They reach the most users (45%+ of Google searches) and you likely already have Google SEO foundations in place. Add schema markup, include cited sources in your content, and strengthen E-E-A-T signals.

**Then address ChatGPT** — It's the most-used standalone AI search tool for tech and business audiences. Focus on freshness (update content monthly), domain authority, and matching your content structure to how ChatGPT formats its responses.

**Then expand to Perplexity** — Especially valuable if your audience includes researchers, early adopters, or tech professionals. Add FAQ schema, publish PDF resources, and write in clear, self-contained paragraphs.

**Copilot and Claude are lower priority** unless your audience skews enterprise/Microsoft (Copilot) or developer/analyst (Claude). But the fundamentals — structured content, cited sources, schema markup — help across all platforms.

**Actions that help everywhere:**
1. Allow all AI bots in robots.txt
2. Implement schema markup (FAQPage, Article, Organization at minimum)
3. Include statistics with named sources in your content
4. Update content regularly — monthly for competitive topics
5. Use clear heading structure (H1 > H2 > H3)
6. Keep page load time under 2 seconds
7. Add author bios with credentials

````

### `agent/skills/ai-seo/SKILL.md`

```md
---
name: ai-seo
description: Make page content citable by AI search — extractable structure, authority signals, and machine-readable files. Use when writing page body copy for AI visibility.
---

# AI SEO

Optimize page content so AI systems can **cite** it — not just rank it. Traditional
SEO gets you ranked; AI SEO gets you **cited** in generated answers.

## Before writing

Ground copy in Context.dev brand and page data. Do not write separate "AI-only"
content — that risks scaled content abuse. Write for people; organize for clarity.

## Cited vs ranked

| Traditional SEO | AI SEO |
|-----------------|--------|
| Rank on page 1 | Get cited as a source |
| Keyword placement | Extractable answer blocks |
| Backlinks | Authority signals + structure |

**Google AI Overviews** follow core Search quality — helpful, people-first content
with strong E-E-A-T. **Other engines** (ChatGPT, Perplexity, Claude) reward
extractable structure, FAQs, comparison tables, and machine-readable files.

When in doubt: write for people, organize for clarity. That satisfies both.

## Three pillars

Apply all three before returning HTML. **Done when** every pillar is addressed.

### 1. Structure — make it extractable

AI systems extract passages, not pages. Every key claim should work standalone.

- Lead each section with a direct answer
- Keep key answer passages to 40–60 words
- Use headings that match how people phrase queries
- Tables beat prose for comparisons; numbered lists beat paragraphs for processes
- Include an FAQ or answer-focused section when it fits page intent

For block templates, see [content-patterns](./references/content-patterns.md).

### 2. Authority — make it citable

- Cite sources with links where claims need backing
- Include specific statistics with dates when source data provides them
- Name authors or expertise when available from source data
- Do not invent statistics, awards, customers, or testimonials

### 3. Presence — machine-readable files

When the generated site should expose agent-readable context:

- `/llms.txt` — product overview and key page links
- `/pricing.md` or `/pricing.txt` — structured pricing when pricing exists in
  source data

For platform-specific ranking factors and robots.txt bot lists, see
[platform-ranking-factors](./references/platform-ranking-factors.md). For OKF
bundles, see [okf](./references/okf.md).

## Extractability checklist

For each priority section, verify:

| Check | Pass when |
|-------|-----------|
| Clear definition in first paragraph | Reader knows what the section covers immediately |
| Self-contained answer blocks | Block makes sense without surrounding context |
| FAQ with natural-language questions | Present when page intent warrants it |
| Schema markup | JSON-LD matches visible content |
| Claims grounded | Every fact traceable to Context.dev or user input |

## Schema for AI

Structured data helps AI systems understand content:

| Content | Schema |
|---------|--------|
| Page | `WebPage`, `Organization` |
| FAQ section | `FAQPage` |
| Product page | `Product` |
| How-to section | `HowTo` |

Schema is not required for Google generative AI, but helps non-Google engines.
Align schema with the on-page SEO checklist in the `seo-audit` skill.

## What not to do

1. Write separate content "for AI" — serve people and AI from the same copy
2. Chunk pages into AI-bait fragments — use normal headings and paragraphs
3. Keyword stuff — it reduces AI visibility
4. Block AI search bots if you want citation (`GPTBot`, `PerplexityBot`, `ClaudeBot`,
   `Google-Extended`)
5. Hide main content behind JS that does not render

For content-type tactics (comparison pages, docs, local), see
[content-types](./references/content-types.md).

```

### `agent/skills/seo-audit/references/ai-writing-detection.md`

```md
# AI Writing Detection

Words, phrases, and punctuation patterns commonly associated with AI-generated text. Avoid these to ensure writing sounds natural and human.

Sources: Grammarly (2025), Microsoft 365 Life Hacks (2025), GPTHuman (2025), Walter Writes (2025), Textero (2025), Plagiarism Today (2025), Rolling Stone (2025), MDPI Blog (2025)

---

## Contents
- Em Dashes: The Primary AI Tell
- Overused Verbs
- Overused Adjectives
- Overused Transitions and Connectors
- Phrases That Signal AI Writing (Opening Phrases, Transitional Phrases, Concluding Phrases, Structural Patterns)
- Filler Words and Empty Intensifiers
- Academic-Specific AI Tells
- How to Self-Check

## Em Dashes: The Primary AI Tell

**The em dash (—) has become one of the most reliable markers of AI-generated content.**

Em dashes are longer than hyphens (-) and are used for emphasis, interruptions, or parenthetical information. While they have legitimate uses in writing, AI models drastically overuse them.

### Why Em Dashes Signal AI Writing
- AI models were trained on edited books, academic papers, and style guides where em dashes appear frequently
- AI uses em dashes as a shortcut for sentence variety instead of commas, colons, or parentheses
- Most human writers rarely use em dashes because they don't exist as a standard keyboard key
- The overuse is so consistent that it has become the unofficial signature of ChatGPT writing

### What To Do Instead

| Instead of | Use |
|------------|-----|
| The results—which were surprising—showed... | The results, which were surprising, showed... |
| This approach—unlike traditional methods—allows... | This approach, unlike traditional methods, allows... |
| The study found—as expected—that... | The study found, as expected, that... |
| Communication skills—both written and verbal—are essential | Communication skills (both written and verbal) are essential |

### Guidelines
- Use commas for most parenthetical information
- Use colons to introduce explanations or lists
- Use parentheses for supplementary information
- Reserve em dashes for rare, deliberate emphasis only
- If you find yourself using more than one em dash per page, revise

---

## Overused Verbs

| Avoid | Use Instead |
|-------|-------------|
| delve (into) | explore, examine, investigate, look at |
| leverage | use, apply, draw on |
| optimise | improve, refine, enhance |
| utilise | use |
| facilitate | help, enable, support |
| foster | encourage, support, develop, nurture |
| bolster | strengthen, support, reinforce |
| underscore | emphasise, highlight, stress |
| unveil | reveal, show, introduce, present |
| navigate | manage, handle, work through |
| streamline | simplify, make more efficient |
| enhance | improve, strengthen |
| endeavour | try, attempt, effort |
| ascertain | find out, determine, establish |
| elucidate | explain, clarify, make clear |

---

## Overused Adjectives

| Avoid | Use Instead |
|-------|-------------|
| robust | strong, reliable, thorough, solid |
| comprehensive | complete, thorough, full, detailed |
| pivotal | key, critical, central, important |
| crucial | important, key, essential, critical |
| vital | important, essential, necessary |
| transformative | significant, important, major |
| cutting-edge | new, advanced, recent, modern |
| groundbreaking | new, original, significant |
| innovative | new, original, creative |
| seamless | smooth, easy, effortless |
| intricate | complex, detailed, complicated |
| nuanced | subtle, complex, detailed |
| multifaceted | complex, varied, diverse |
| holistic | complete, whole, comprehensive |

---

## Overused Transitions and Connectors

| Avoid | Use Instead |
|-------|-------------|
| furthermore | also, in addition, and |
| moreover | also, and, besides |
| notwithstanding | despite, even so, still |
| that being said | however, but, still |
| at its core | essentially, fundamentally, basically |
| to put it simply | in short, simply put |
| it is worth noting that | note that, importantly |
| in the realm of | in, within, regarding |
| in the landscape of | in, within |
| in today's [anything] | currently, now, today |

---

## Phrases That Signal AI Writing

### Opening Phrases to Avoid
- "In today's fast-paced world..."
- "In today's digital age..."
- "In an era of..."
- "In the ever-evolving landscape of..."
- "In the realm of..."
- "It's important to note that..."
- "Let's delve into..."
- "Imagine a world where..."

### Transitional Phrases to Avoid
- "That being said..."
- "With that in mind..."
- "It's worth mentioning that..."
- "At its core..."
- "To put it simply..."
- "In essence..."
- "This begs the question..."

### Concluding Phrases to Avoid
- "In conclusion..."
- "To sum up..."
- "By [doing X], you can [achieve Y]..."
- "In the final analysis..."
- "All things considered..."
- "At the end of the day..."

### Structural Patterns to Avoid
- "Whether you're a [X], [Y], or [Z]..." (listing three examples after "whether")
- "It's not just [X], it's also [Y]..."
- "Think of [X] as [elaborate metaphor]..."
- Starting sentences with "By" followed by a gerund: "By understanding X, you can Y..."

---

## Filler Words and Empty Intensifiers

These words often add nothing to meaning. Remove them or find specific alternatives:

- absolutely
- actually
- basically
- certainly
- clearly
- definitely
- essentially
- extremely
- fundamentally
- incredibly
- interestingly
- naturally
- obviously
- quite
- really
- significantly
- simply
- surely
- truly
- ultimately
- undoubtedly
- very

---

## Academic-Specific AI Tells

| Avoid | Use Instead |
|-------|-------------|
| shed light on | clarify, explain, reveal |
| pave the way for | enable, allow, make possible |
| a myriad of | many, numerous, various |
| a plethora of | many, numerous, several |
| paramount | very important, essential, critical |
| pertaining to | about, regarding, concerning |
| prior to | before |
| subsequent to | after |
| in light of | because of, given, considering |
| with respect to | about, regarding, for |
| in terms of | regarding, for, about |
| the fact that | that (or rewrite sentence) |

---

## How to Self-Check

1. Read your text aloud. If phrases sound unnatural in speech, revise them
2. Ask: "Would I say this in a conversation with a colleague?"
3. Check for repetitive sentence structures
4. Look for clusters of the words listed above
5. Ensure varied sentence lengths (not all similar length)
6. Verify each intensifier adds genuine meaning

```

### `agent/skills/seo-audit/references/international-seo.md`

```md
# International SEO: Evidence & Sources

Detailed evidence backing the International SEO & Localization section of the SEO Audit skill. Organized by topic with source URLs and key quotes.

---

## Hreflang

### Placement Methods

Google supports three equivalent methods: HTML `<link>` in `<head>`, HTTP `Link` headers, and XML sitemap `<xhtml:link>` elements. Google confirmed no method is prioritized over another.

Google combines signals from both HTML and sitemaps. If the same language-region pair points to different URLs across methods, Google drops that pair rather than guessing.

- [Google Search Central: Localized Versions](https://developers.google.com/search/docs/specialty/international/localized-versions)
- [SEJ: Google Combines Hreflang Signals](https://www.searchenginejournal.com/google-combines-hreflang-signals-from-html-sitemaps/389219/)

### Reciprocal Requirement

Google's docs: "If page X links to page Y, page Y must link back to page X. If not, those annotations may be ignored or not interpreted correctly."

Every page must include itself (self-referencing) in the hreflang set. Missing self-referencing is the #1 error found by Semrush audits. A study of 374,756 domains found 67% of hreflang implementations had issues.

- [Google Search Central: Localized Versions](https://developers.google.com/search/docs/specialty/international/localized-versions)
- [Semrush: 9 Common Hreflang Errors](https://www.semrush.com/blog/hreflang-errors/)
- [SE Land: 31% of International Websites Contain Hreflang Errors](https://searchengineland.com/study-31-of-international-websites-contain-hreflang-errors-395161)

### x-default

Introduced April 2013. Designates the fallback page for users whose language/region matches no declared variant. Can point to the same URL as one of the language-specific alternates. Must be included in the complete set of annotations on every variant page.

- [Google Blog: x-default hreflang](https://developers.google.com/search/blog/2013/04/x-default-hreflang-for-international-pages)
- [Google Blog: How x-default can help you (2023)](https://developers.google.com/search/blog/2023/05/x-default)

### Language & Region Codes

Language: ISO 639-1 (2-letter). Region: ISO 3166-1 Alpha 2 (2-letter). Format: `language[-script][-region]`.

You cannot specify a region code alone. Common mistakes: `en-UK` (should be `en-GB`), `es-419` (not ISO 3166-1). A study found 8.9% of sites using hreflang contain invalid language codes.

- [Google Search Central: Localized Versions](https://developers.google.com/search/docs/specialty/international/localized-versions)
- [SE Land: 31% Study](https://searchengineland.com/study-31-of-international-websites-contain-hreflang-errors-395161)

### Hreflang at Scale (20+ locales)

With 20 locales, HTML `<head>` hreflang adds ~1.5KB per page for zero user benefit. Sitemap-based hreflang has zero runtime performance impact. `<xhtml:link>` child elements do NOT count toward the 50,000 URL sitemap limit (only `<loc>` elements count).

John Mueller recommends focusing hreflang on pages receiving wrong-language traffic, not every page: "I wouldn't do it for any of the other pages of the site because it's so complex & hard to manage."

- [SERoundtable: Child Elements Don't Count](https://www.seroundtable.com/google-child-elements-dont-count-towards-sitemap-url-limit-34377.html)
- [SERoundtable: Where To Focus Hreflang](https://www.seroundtable.com/using-hreflang-34127.html)
- [Yoast: hreflang Ultimate Guide](https://yoast.com/hreflang-ultimate-guide/)

### Google vs Bing

Bing treats hreflang as a "weak signal." Bing relies on `content-language` meta tag, HTML `lang` attribute, ccTLDs, and server location. Yandex supports hreflang like Google.

For both engines: implement hreflang (Google/Yandex) + `<html lang="...">` + `<meta http-equiv="content-language">` (Bing).

- [Digital Ready Marketing: Bing Doesn't Use Hreflang](https://digitalreadymarketing.com/bing-doesnt-use-hreflang-annotation-what-does-it-use/)
- [Yoast: hreflang Ultimate Guide](https://yoast.com/hreflang-ultimate-guide/)

---

## Canonicalization & i18n

### Self-Referencing Canonicals

Each locale page must canonical to itself. John Mueller: "Don't use a rel=canonical across languages/countries, only use it on a per-country/language basis."

Google's docs: "Specify a canonical page in the same language, or the best possible substitute language if a canonical doesn't exist for the same language."

- [John Mueller: hreflang canonical](https://johnmu.com/hreflang-canonical/)
- [Google: Consolidate Duplicate URLs](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls)

### Canonical Overrides Hreflang

Mueller: "If your canonical is pointing somewhere else, Google will follow that and ignore your hreflang annotation." The canonical URL must be one of the URLs in the hreflang set, or all hreflang markup is ignored.

Google also states: "Google prefers URLs that are part of hreflang clusters for canonicalization" -- when signals align, hreflang strengthens canonical selection.

- [John Mueller: hreflang canonical](https://johnmu.com/hreflang-canonical/)
- [SEJ: Hreflang Tags Are Hints](https://www.searchenginejournal.com/google-reminds-that-hreflang-tags-are-hints-not-directives/546428/)
- [Google: Consolidate Duplicate URLs](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls)

### Near-Duplicate Regional Variants

Mueller (2023 Office Hours): "If the content is completely the same, and we can't tell any difference, then for simplicity and user experience we may just show one version -- even if hreflang is present."

Google's duplicate detection runs BEFORE hreflang evaluation. To keep both versions indexed, you need substantive content differences beyond currency symbols.

- [International Web Mastery: Same-Language Duplicate Pages](https://internationalwebmastery.com/blog/how-google-handles-canonicalization-of-same-language-duplicate-near-duplicate-pages/)
- [Google: Managing Multi-Regional Sites](https://developers.google.com/search/docs/specialty/international/managing-multi-regional-sites)

### Pagination Across Locales

Google: "Don't use the first page of a paginated sequence as the canonical page. Instead, give each page its own canonical URL." Each paginated page in each locale gets self-referencing canonical. `rel="next/prev"` deprecated March 2019.

- [Google: Pagination Best Practices](https://developers.google.com/search/docs/specialty/ecommerce/pagination-and-incremental-page-loading)

---

## International Sitemaps

### Structure

Each `<url>` entry includes `<xhtml:link>` alternates for every locale. Requires `xmlns:xhtml="http://www.w3.org/1999/xhtml"` namespace.

Split sitemaps by content type, not by locale. Splitting by locale creates maintenance problems because every locale sitemap must reference every other locale (reciprocal requirement).

- [Google Search Central: Localized Versions](https://developers.google.com/search/docs/specialty/international/localized-versions)
- [Lumar: How Google Handles Hreflang](https://www.lumar.io/office-hours/hreflang/)

### Size Limits

50,000 URLs / 50MB uncompressed per sitemap. Only `<loc>` elements count toward the 50K limit. But with 20 hreflang alternates per entry, the 50MB file size limit becomes the bottleneck. Plan for 2,000-5,000 URLs per sitemap when using full hreflang.

- [Google: Build and Submit a Sitemap](https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap)
- [SERoundtable: Sitemap 50,000 Limit](https://www.seroundtable.com/google-sitemap-50-000-limit-based-on-location-urls-not-alternative-urls-33843.html)

### Submission

Submit the sitemap index in Search Console AND reference it in robots.txt. Individual child sitemaps can be submitted separately for per-sitemap reporting.

- [Google: Build and Submit a Sitemap](https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap)

### Next.js Caveat

Next.js `alternates.languages` does NOT automatically include a self-referencing `<xhtml:link>` for the `<loc>` URL. You must explicitly include the `<loc>` URL's own language in the `languages` object.

- [Next.js Docs: sitemap.xml](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap)

---

## URL Structure

### Strategies Compared

Google treats subdirectories and subdomains equivalently. Mueller: "From our point of view...they say subdomains and subdirectories are essentially equivalent."

URL parameters (`?lang=en`) are explicitly "Not recommended" per Google docs.

- [Google: Managing Multi-Regional Sites](https://developers.google.com/search/docs/specialty/international/managing-multi-regional-sites)

### Default Language

Mueller recommends: set `/` as x-default, put each language in its own prefix. Without marking `/` as x-default, "to Google it can look like '/' is a separate page from the others."

- [Google Blog: x-default](https://developers.google.com/search/blog/2023/05/x-default)
- [Google Blog: Creating the Right Homepage](https://developers.google.com/search/blog/2014/05/creating-right-homepage-for-your)

### Content Negotiation / IP Redirects

Google strongly advises against locale-adaptive pages. Googlebot crawls from US IPs and does not send Accept-Language headers. Separate URLs + hreflang are required.

- [Google: Locale-Adaptive Pages](https://developers.google.com/search/docs/specialty/international/locale-adaptive-pages)

### Trailing Slash Consistency

Mueller: trailing slash is "a significant part of the URL and will change the URL if it's there or not." Pick one format for all locale paths, internal links, canonicals, hreflang, and sitemaps.

Mueller (2025): "Consistency is the biggest technical SEO factor."

- [SERoundtable: Consistency Is The Biggest Technical SEO Factor](https://www.seroundtable.com/google-consistency-seo-40427.html)

### Search Console Geotargeting

The International Targeting report is deprecated. Google now relies entirely on hreflang, content language analysis, and linking patterns. You can add subdirectory properties for per-locale reporting.

- [Google Support: International Targeting Deprecated](https://support.google.com/webmasters/answer/12474899?hl=en)

### Framework Locale Modes

Use `localePrefix: 'always'` (next-intl) or equivalent. Never hide locale from URLs -- Google needs unique URLs per language. Using `'never'` mode disables alternate links entirely.

- [next-intl: Routing Configuration](https://next-intl.dev/docs/routing/configuration)
- [Next.js Discussion #18419](https://github.com/vercel/next.js/discussions/18419)

---

## Content Quality Across Locales

### Auto-Translated Content (2025 Stance)

Google removed longstanding guidance advising against auto-translated content in mid-2025. Current stance: "Our policies do not strictly define content that has been translated by AI as spam." The scaled content abuse policy mentions translation as a possible vector, but does not ban it.

Reddit scaled AI translations to 35+ languages with Google's knowledge. The key distinction is intent and quality, not the method.

- [Google Spam Policies](https://developers.google.com/search/docs/essentials/spam-policies)
- [Glenn Gabe: Auto-Translating Content](https://www.gsqi.com/marketing-blog/auto-translating-content-google-scaled-content-abuse/)
- [SE Land: Reddit AI Translations](https://searchengineland.com/google-comments-on-reddits-use-of-ai-to-translate-its-pages-456908)

### Thin Locale Pages

Google: "Localized versions of a page are only considered duplicates if the main content of the page remains untranslated." Pages with only translated boilerplate get clustered as duplicates.

Do NOT use noindex for unwanted locale pages (wastes crawl budget). Do NOT canonical cross-locale (conflicts with hreflang). Best approach: don't create locale pages you can't make genuinely helpful.

- [Google: Localized Versions](https://developers.google.com/search/docs/specialty/international/localized-versions)
- [Google: Crawl Budget Management](https://developers.google.com/search/docs/crawling-indexing/large-site-managing-crawl-budget)

### Helpful Content System Impact

Merged into core ranking March 2024. Site-wide signal: "any content -- not just unhelpful content -- on sites determined to have relatively high amounts of unhelpful content overall is less likely to perform well in Search."

Low-quality translated pages can drag down the entire site. This is the strongest argument against creating locale pages that aren't genuinely helpful.

- [Google Blog: Helpful Content Update](https://developers.google.com/search/blog/2022/08/helpful-content-update)
- [Amsive: What Changed in 2024](https://www.amsive.com/insights/seo/googles-helpful-content-update-ranking-system-what-happened-and-what-changed-in-2024/)

### Partial Translation

Google: "Translating only the boilerplate text of your pages while keeping the bulk of your content in a single language...can create a bad user experience." Google uses visible content (not lang attribute) to determine page language.

Translate ALL content on a page if you create a locale version. Untranslated metadata (title, description) in the wrong language reduces CTR.

- [Google: Managing Multi-Regional Sites](https://developers.google.com/search/docs/specialty/international/managing-multi-regional-sites)

### Crawl Budget

Only a concern for 1M+ pages or 10K+ pages changing daily. But alternate URLs (hreflang targets) do consume crawl budget. Broken hreflang links waste budget AND invalidate signals.

- [Google: Crawl Budget Management](https://developers.google.com/search/docs/crawling-indexing/large-site-managing-crawl-budget)
- [Google Blog: Crawl Budget](https://developers.google.com/search/blog/2017/01/what-crawl-budget-means-for-googlebot)

### Locale-Specific Signals

Google identifies audience via: "local addresses and phone numbers on the pages, the use of local language and currency, links from other local sites, or signals from your Business Profile."

- [Google: Managing Multi-Regional Sites](https://developers.google.com/search/docs/specialty/international/managing-multi-regional-sites)

```

### `agent/skills/seo-audit/SKILL.md`

```md
---
name: seo-audit
description: Apply on-page SEO checks when building a single branded HTML page — metadata, headings, schema, links, and images.
---

# Page SEO checklist

Use when planning or reviewing metadata, headings, canonical tags, internal links,
image alt text, and schema for a page this agent is **building** — not for full-site
audit reports unless the user explicitly asks.

## Schema detection limitation

`web_fetch` and `curl` cannot reliably detect structured data. Many CMS plugins inject
JSON-LD via client-side JavaScript — it will not appear in static HTML or `web_fetch`
output (which strips `<script>` tags).

Do not report "no schema found" from `web_fetch` or `curl` alone. When validating
schema on a live site, use the browser tool, Google Rich Results Test, or Screaming
Frog.

## Priority order for page building

1. **Indexability** — page is meant to be indexed; no accidental `noindex`
2. **On-page metadata** — title, description, canonical, Open Graph, Twitter cards
3. **Heading structure** — one `<h1>`, logical hierarchy, keyword-aligned sections
4. **Content quality** — answers search intent; claims grounded in source data
5. **Schema** — JSON-LD matching page intent (`WebPage`, `Organization`, `FAQPage`,
   `Product`, or `Service`)

## On-page checks

Apply every check before returning HTML. **Done when** each item is addressed or
marked N/A with a reason.

### Title and meta

- Unique `<title>` with primary keyword near the start (50–60 visible chars)
- Unique meta description with value proposition (150–160 chars)
- Self-referencing canonical URL on the page being built
- Open Graph and Twitter card tags aligned with title and description

### Headings and content

- Exactly one `<h1>` containing the primary keyword
- Logical hierarchy (`h1` → `h2` → `h3`); no skipped levels
- Primary keyword in the first 100 words when natural
- Descriptive link text — never "click here" or bare URLs
- Accessible `alt` on every image; decorative images use `alt=""`

### Structured data

- JSON-LD in `application/ld+json` matching page intent
- Claims in schema match visible page content and source data
- FAQ schema only when an FAQ section exists on the page

### Technical notes for generated pages

- `<html lang="...">` set correctly
- No remote scripts unless the user explicitly asked
- Image dimensions set when known to avoid layout shift

## Out of scope

Unless the user explicitly requests an audit report, do not produce a full-site
technical SEO audit. For deep dives on international SEO or AI-writing patterns, see
[international-seo](./references/international-seo.md) and
[ai-writing-detection](./references/ai-writing-detection.md).

## Output when building

Return SEO notes with: target search intent, primary keyword, secondary topics,
schema types used, and source URLs — per the agent output contract.

```

### `evals/evals.config.ts`

```ts
import { defineEvalConfig } from "eve/evals";

export default defineEvalConfig({
  timeoutMs: 120_000,
});

```

### `evals/missing-domain-asks.eval.ts`

```ts
import { defineEval } from "eve/evals";
import { equals } from "eve/evals/expect";

export default defineEval({
  description:
    "Asks for the domain before doing any generation or Context.dev work when none is provided.",
  async test(t) {
    await t.send(`
Build me an SEO-optimized landing page.

No domain has been provided. Proceed according to your instructions: ask for the domain before doing any generation work. Do not call any Context.dev tools and do not produce any HTML yet.
`);

    t.succeeded();
    t.noFailedActions();
    const reply = t.reply ?? "";
    t.check(reply.toLowerCase().includes("domain"), equals(true).gate());
    t.check(reply.includes("?"), equals(true).gate());
    t.check(reply.toLowerCase().includes("<!doctype"), equals(false).gate());
  },
});

```

### `evals/page-structure-contract.eval.ts`

```ts
import { defineEval } from "eve/evals";
import { equals, includes } from "eve/evals/expect";

export default defineEval({
  description:
    "Builds a complete on-brand HTML page from provided Context.dev data with the mandated SEO structure, without inventing testimonials, pricing, or statistics.",
  timeoutMs: 300_000,
  async test(t) {
    await t.send(`
Build the SEO page for acme.dev as a homepage.

The Context.dev brand lookup for acme.dev already returned:

{
  "name": "Acme Dev Tools",
  "description": "Acme Dev Tools ships a CLI and dashboard that help teams catch flaky tests before deploys.",
  "industry": "developer tools",
  "colors": { "primary": "#1D4ED8", "background": "#F8FAFC", "text": "#0F172A" },
  "fonts": { "heading": "Inter", "body": "Inter" }
}

The homepage markdown returned only a short tagline: "Catch flaky tests before your users do." No testimonials, customer names, statistics, awards, or pricing information is available.

All the Context.dev data you need is provided above, so do not call Context.dev tools again in this run. Proceed according to your instructions: produce one complete HTML document in a single fenced html code block, grounded only in the data above — do not invent testimonials, customer names, statistics, awards, or pricing. Include the SEO notes section after the page.
`);

    t.succeeded();
    t.noFailedActions();

    const reply = t.reply ?? "";
    const replyLower = reply.toLowerCase();
    t.check(replyLower, includes("<!doctype html").gate());
    t.check(replyLower, includes("<html lang").gate());
    t.check(replyLower, includes("<title").gate());
    t.check(replyLower, includes('name="description"').gate());
    const h1Count = replyLower.split("<h1").length - 1;
    t.check(h1Count === 1, equals(true).gate());
    t.check(replyLower, includes('rel="canonical"').soft());
    t.check(replyLower, includes("application/ld+json").soft());
    t.check(replyLower, includes("seo notes").soft());
    t.check(replyLower.includes("<script src=\"http"), equals(false).gate());
    t.check(reply, includes("Acme Dev Tools").gate());
  },
});

```

### `agent/README.md`

````md
# Branded SEO Page Builder

An on-demand Eve agent that turns a domain into a complete SEO-optimized HTML
page. It connects to Context.dev's hosted MCP server to resolve brand metadata,
scrape homepage content, and extract design-system signals, then applies the
bundled `seo-audit` and `ai-seo` skills to produce search-ready static HTML.

## What it does

1. **Connects to Context.dev MCP** — uses the hosted MCP server at
   `https://context-dev.stlmcp.com`, authenticated with the
   `x-context-dev-api-key` header.
2. **Resolves brand data with Context.dev** — pulls company name, description,
   colors, logos, industry labels, and related metadata from a domain.
3. **Scrapes source content** — reads the homepage or a user-provided page URL as
   clean markdown so the generated copy is grounded in existing brand language.
4. **Extracts style cues** — optionally pulls Context.dev styleguide data for
   colors, typography, spacing, shadows, and component cues.
5. **Generates SEO HTML** — returns one complete HTML document with semantic
   sections, metadata, Open Graph tags, Twitter card tags, accessible image alt
   text, and JSON-LD schema.
6. **Optimizes for AI search** — loads the bundled `ai-seo` skill so the page is
   extractable and citable by answer engines while staying people-first.

## Skills

- **seo-audit** — technical and on-page SEO checks for metadata, headings,
  canonicalization, schema, accessibility, and crawlability.
- **ai-seo** — answer engine optimization patterns for extractable sections,
  answer blocks, FAQs, and LLM-friendly structure.

Both skills are vendored from
`https://github.com/coreyhaines31/marketingskills/tree/main/skills`.

## Installation

```bash
npx shadcn@latest add @evex/branded-seo-page-builder
```

Install the public runtime dependencies listed by the registry item if your Eve
app does not already have them.

## Configuration

Copy `.env.example` into your Eve app environment and fill in the Context.dev
credential.

```env
CONTEXT_DEV_API_KEY=ctxt_secret_...
```

`CONTEXT_API_KEY` is also supported as a fallback for projects that already use
that name, but `CONTEXT_DEV_API_KEY` is the documented Context.dev standard. The
Eve MCP connection sends the resolved key as the `x-context-dev-api-key` header.

Never expose the Context.dev key to browser-side code. This agent sends it only
from the Eve MCP connection runtime.

## Usage

Ask the agent for a page from a domain:

```text
Create an SEO-optimized landing page for linear.app.
```

You can also provide a specific source page:

```text
Build a product page from https://example.com/product and target "AI support automation".
```

The agent returns:

1. A complete HTML document in one fenced `html` block.
2. SEO notes with search intent, primary keyword, secondary topics, schema types,
   and Context.dev source URLs.
3. Assumptions when any copy was inferred instead of directly sourced.

## Smoke test

1. Set `CONTEXT_DEV_API_KEY` in the Eve app environment.
2. Start the app in development:

   ```bash
   pnpm dev
   ```

3. In your Eve chat/client, ask:

   ```text
   Generate an SEO HTML homepage for stripe.com.
   ```

4. Confirm the agent uses the `context-dev` MCP connection, then returns a full
   `<!doctype html>` document with metadata, JSON-LD, semantic sections, and SEO
   notes listing Context.dev source URLs.

## Troubleshooting

- **`CONTEXT_DEV_API_KEY is required`** — set `CONTEXT_DEV_API_KEY` in the Eve app
  environment and restart the server.
- **`Context.dev API 401`** — the key is missing, revoked, or copied incorrectly.
- **`Context.dev API 408` or `429`** — the MCP call hit a cold-start timeout or
  rate limit. Retry later or lower concurrent usage.
- **No brand facts in the HTML** — Context.dev did not return enough brand data
  and the agent refused to invent claims. Provide more source copy or a specific
  page URL.
- **Unexpected visual style** — pass a specific source page URL or disable
  styleguide use by asking the agent to call Context without styleguide data.

## Development

```bash
pnpm install
pnpm info
pnpm build
```

Run `pnpm typecheck` while editing the Context MCP connection.

````

### `.env.example`

```
CONTEXT_DEV_API_KEY=
CONTEXT_API_KEY=

```