V1.0-ALPHASTATUS: ALPHA · MIT LICENSE

SEO.MD

THE OPEN STANDARD FOR AI ENGINE OPTIMIZATION

01.OVERVIEW

SEO.md is a plain-text protocol specification file that enables founders, developers, and content teams to declare their brand's AI search intent in a version-controlled, human-readable format.

It is part of a growing family of open standards — alongside CLAUDE.md, AGENTS.md, and DESIGN.md - that make machine-readable context a first-class part of every software project.

Core Principle

AN SEO.MD FILE IS THE SINGLE SOURCE OF TRUTH FOR YOUR BRAND'S AI SEARCH STRATEGY

SEO.md separates what the founder declares from what the platform writes back. This dual-layer model ensures that strategic intent is always human-authored, while analytical intelligence is machine-populated.

02.FILE FORMAT

An SEO.md file consists of two parts:

FOUNDER DECLARES

NO PREFIX

Fields without a prefix are owned by the founder. Edit freely. Commit to version control.

PLATFORM WRITES BACK

_ANALYSIS: PREFIX

Fields prefixed with _analysis: are written by the connected platform. Do not edit manually.

The file uses Markdown headings (##) as section delimiters, with YAML-formatted fields under each section. This makes it readable in any text editor, diff-able in any Git client, and parseable by any YAML parser.

# SEO.md

## {{brand}}

### spec v1.0 | https://seomd.dev

#### generated: {{date}}

## FIELD OWNERSHIP
### no prefix     = founder declares (you own this)
### _analysis:    = platform writes back (do not edit manually)

## Site

site:
  type: saas           # blog | saas | ecommerce | local | marketplace
  domain: {{domain}}
  canonical: https://{{domain}}
  locale: en-US
  launched: null       # YYYY-MM-DD

03.SITE TYPES

The site.type field determines which page templates and intent patterns the CLI scaffolds. Each type has a different required page set.

Type	Value	Required Pages	Primary Use Case
`Blog`	`blog`	homepage, category, article, author, about	Content publishers, newsletters
`SaaS`	`saas`	homepage, features, pricing, comparison, blog	Software products, platforms
`eCommerce`	`ecommerce`	homepage, category, product, cart, checkout	Online stores
`Local`	`local`	homepage, services, location, reviews	Local businesses
`Marketplace`	`marketplace`	homepage, listing, search, seller	Two-sided platforms

04.SITE

Core site metadata. The site section identifies the type, domain, canonical URL, and locale of the project.

FieldTypeReq.Description

site.typestringrequired

Site type identifier. One of: blog, saas, ecommerce, local, marketplace.

site.domainstringrequired

The primary domain, without protocol (e.g. example.com).

site.canonicalurlrequired

The canonical HTTPS URL (e.g. https://example.com).

site.localestringoptional

BCP 47 locale code. Default: en-US.

site.launcheddateoptional

Launch date in YYYY-MM-DD format.

05.IDENTITY

Brand identity and social presence. Defines how your brand is named, positioned, and discovered across platforms.

FieldTypeReq.Description

identity.brandstringrequired

The canonical brand name exactly as it should appear in citations.

identity.taglinestringoptional

A short brand tagline, 10 words or fewer.

identity.social.twitterstringoptional

Twitter/X handle (without @).

identity.social.linkedinurloptional

LinkedIn company page URL.

identity.social.githubstringoptional

GitHub organization or user handle.

identity.schema_org_typestringoptional

Schema.org type. Default: Organization.

06.KEYWORDS

Keyword strategy. Define your primary keyword, secondary terms, negative keywords that dilute your intent signal, and competitor terms for monitoring.

FieldTypeReq.Description

keywords.primarystringrequired

The single most important keyword your brand must own in AI search results.

keywords.secondarystring[]optional

Supporting keyword cluster. 3–10 terms recommended.

keywords.negativestring[]optional

Terms that dilute intent signal. Platform uses these to filter noise from analysis.

keywords.competitor_termsstring[]optional

Competitor brand terms to monitor for citation displacement.

keywords.category_termsstring[]optional

Unbranded category queries (e.g., "best ai seo tools").

keywords.long_tailstring[]optional

Long-tail keyword variations.

keywords._analysisobjectoptional

Platform-populated search volume, intent type, trend data, and recommendations.

← platform writes back

07.INTENT

AI query intent mapping. List the exact queries your buyers type into AI engines across five intent categories. These are fed directly to the citation analysis engine.

FieldTypeReq.Description

intent.informationalIntentBlockrequired

Priority: critical. Queries seeking information about your category (e.g., "what is AI SEO").

intent.comparisonIntentBlockoptional

Queries comparing your brand to competitors.

intent.transactionalIntentBlockoptional

Queries with purchase or trial intent.

intent.reputationalIntentBlockoptional

Queries about brand credibility, reviews, problems.

intent.categoryIntentBlockoptional

Unbranded category-level queries (e.g., "best SEO tools 2026").

intent._analysisobjectoptional

Platform-populated citation rates, gap scores, and competitor citations per intent category.

← platform writes back

08.PAGES

Page inventory and citation targets. List every page that should appear in AI search results with its target keyword and status.

FieldTypeReq.Description

pages.site_typestringrequired

Mirrors site.type. Used by the CLI to scaffold the required page set.

pages.requiredPageDef[]required

Array of page definitions. Each has: id, url, primary_keyword, status (live|draft|planned), priority.

pages._analysisobjectoptional

Platform analysis: citation rates per page, missing pages, and build order recommendations.

← platform writes back

09.COPY

Content quality standards. Declare minimum word counts, reading level targets, and structural copy rules that the validator checks against.

FieldTypeReq.Description

copy.h1_contains_primary_keywordbooleanoptional

Require H1 to contain the page's primary keyword. Default: true.

copy.meta_description_lengthstringoptional

Target meta description length range (e.g., "150-160").

copy.min_word_countobjectoptional

Minimum word counts by page type: homepage, feature_page, blog_post, comparison_page.

copy.reading_levelnumberoptional

Target Flesch-Kincaid grade level. Default: 8.

10.STRUCTURE

Content structure rules for AI scannability. These rules are checked by the validator and inform the platform's content gap analysis.

FieldTypeReq.Description

structure.answer_firstbooleanoptional

Require a direct answer in the first 50 words of each page. Default: true.

structure.faq_section_requiredbooleanoptional

Require a FAQ section on all key pages. Default: true.

structure.faq_minimum_questionsnumberoptional

Minimum number of FAQ entries. Default: 6.

structure.statistics_per_pagenumberoptional

Minimum data points with citations per page. Default: 2.

structure.heading_hierarchystringoptional

Heading hierarchy enforcement. Options: strict (H1>H2>H3, no skipping).

11.AUTHORITY

E-E-A-T signals. Declare your Experience, Expertise, Authority, and Trust signals so the platform can assess and improve your citation authority score.

FieldTypeReq.Description

authority.cite_sourcesbooleanoptional

Require links to primary sources in all content. Default: true.

authority.expert_quotesbooleanoptional

Include expert quotes in content. Default: false.

authority.eeat_signals.experiencestringoptional

Description of your experience signal (e.g., "5 years running SEO campaigns").

authority.eeat_signals.expertisestringoptional

Description of your expertise signal.

authority.eeat_signals.authoritystringoptional

Description of your authority signal (e.g., "cited in TechCrunch").

authority.eeat_signals.truststringoptional

Description of your trust signal (e.g., "SOC2 Type II certified").

12.SCHEMA

JSON-LD structured data declarations. Specify which Schema.org types and structured data patterns the validator should enforce across your pages.

FieldTypeReq.Description

schema.typesstring[]required

Schema.org types to implement (e.g., Article, FAQPage, BreadcrumbList, Product).

schema.faq_schemabooleanoptional

Require FAQPage schema on all pages with FAQ sections. Default: true.

schema.breadcrumb_schemabooleanoptional

Require BreadcrumbList schema. Default: true.

schema.organization_schemabooleanoptional

Require Organization schema on homepage. Default: true.

13.CRAWL

Bot access and indexing rules. Declare your sitemap location, robots.txt path, and the full list of AI bots you permit to crawl your content.

FieldTypeReq.Description

crawl.sitemapurloptional

Path to your XML sitemap. Default: /sitemap.xml.

crawl.robots_txtpathoptional

Path to robots.txt. Default: /robots.txt.

crawl.allow_ai_botsbooleanoptional

Master switch to allow or block all AI crawlers. Default: true.

crawl.allowed_botsstring[]optional

Explicit bot allowlist: Googlebot, Bingbot, PerplexityBot, ChatGPT-User, GPTBot, ClaudeBot, anthropic-ai, cohere-ai.

crawl.disallowstring[]optional

URL patterns to exclude from all crawlers (e.g., /admin, /api/*).

14.AEO

AI Engine Optimization rules. This section configures how your brand interacts with AI search engines — the most important section for citation optimization.

Critical Requirement

ANSWER_FIRST_FORMAT: TRUE IS REQUIRED FOR ALL AI ENGINE CITATION OPTIMIZATION

aeo.answer_first_formatbooleanrequired

Require direct answers in the first paragraph of every page. Critical for AI citation.

aeo.faq_on_all_key_pagesbooleanoptional

Require FAQ sections on all priority 1-3 pages. Default: true.

aeo.structured_data_prioritystringoptional

Structured data priority level: high | medium | low. Default: high.

aeo.content_freshness_targetstringoptional

How often key pages must be updated (e.g., 30d, 7d). Default: 30d.

aeo.competitors_to_monitorstring[]optional

List of competitor domains to track for citation displacement.

aeo._analysisobjectoptional

Platform data: overall citation rate, gap score, engines tracked, and last analysis timestamp.

← platform writes back

15.MONITORING

Sync and alert configuration. Controls how and when the connected platform updates your _analysis blocks.

monitoring.sync_schedulestringoptional

How often the platform syncs: monthly | weekly | on_demand. Default: monthly.

monitoring.auto_commitbooleanoptional

Allow the platform to commit _analysis updates directly to your repo. Default: false.

monitoring.pr_modebooleanoptional

Open a PR with _analysis updates instead of committing directly. Default: true.

monitoring.branchstringoptional

Target branch for sync commits or PRs. Default: main.

monitoring.alert_on_gap_score_abovenumberoptional

Alert when gap score exceeds this threshold. Range: 0–100. Default: 80.

monitoring.alert_on_citation_dropbooleanoptional

Alert if citation rate drops between analysis cycles. Default: true.

16.PLATFORM

Platform connection settings. Connect a provider to enable live _analysis writeback.

platform.providerstringoptional

Connected provider: foxcite | manual | ahrefs | semrush | null.

platform.project_idstringoptional

Platform project or workspace ID.

Security

API keys are loaded from the SEOMD_API_KEY environment variable. Never commit API keys to version control. Add .env to your .gitignore.

17.VERSIONING

The SEO.md spec follows a lifecycle from alpha to stable.

ALPHA

Current. Spec is being validated against real-world usage. Breaking changes possible.

BETA

Spec is feature-complete. Minor breaking changes only with migration guides.

STABLE

Spec is finalized. Only additive, backwards-compatible changes allowed.