# SEO Audit Report Template

Scaffold for new SEO audit projects. Copy this into your pyramid root.

```markdown
# SEO Audit: [Site/Page URL]

**Audit date:** YYYY-MM-DD
**Auditor:** seo-specialist profile
**Scope:** [Full site / Single page / Content strategy]

---

## L1 Summary

### Overall Health: [Good / Fair / Poor]
### Score: [N/100]

### Priority Findings
1. [Critical] → [Action]
2. [Critical] → [Action]

### Moderate Findings
1. [Important] → [Action]

### Quick Wins
1. [Low effort, high impact] → [Action]

---

## L2 Analysis Files

### Technical SEO
- Crawlability and indexability
- Page speed / Core Web Vitals
- Mobile-friendliness
- HTTPS and security
- Canonical URLs and hreflang
- Sitemap and robots.txt

### On-Page SEO
- Title tags and meta descriptions
- Heading structure
- Keyword usage
- Content quality and length
- Internal linking
- Image optimization
- URL structure

### Schema Validation
- JSON-LD structure
- Schema.org types used
- Rich result eligibility
- Validation results

### Content Gap Analysis
- Target keywords
- Current rankings
- Competitor analysis
- Gap identification
- Priority recommendations

---

## L3 Dossiers

### Raw Data
- Full crawl results
- Schema validation output
- Keyword research data
- Competitor SERP data

### Methodology Notes
- Tools used
- Assumptions and limitations
- Data collection dates

{
  "schema_version": 1,
  "skill_name": "seo",
  "evals": [
    {
      "id": "technical-audit",
      "case_set": "dev",
      "prompt": "Audit this public page for crawlability, indexability, metadata, structured data, and internal-link problems.",
      "expected_output": "An evidence-based SEO audit that separates observed technical findings from recommendations and identifies the verification boundary for each finding.",
      "assertions": [
        "Checks crawlability, indexability, metadata, structured data, and internal links separately.",
        "Distinguishes observed defects from proposed fixes.",
        "Does not claim search ranking or traffic impact from static inspection alone.",
        "Provides concrete verification steps for proposed changes."
      ]
    },
    {
      "id": "geo-terminology-routing",
      "case_set": "regression",
      "prompt": "Should we create separate AEO and GEO skills, or handle them in SEO? Explain the boundaries and route the work.",
      "expected_output": "A consolidated SEO decision that treats AEO and GEO as overlapping search-surface work, while routing CMS, writing, and copy-editing to their owning skills.",
      "assertions": [
        "Defines SEO as the umbrella and AEO/GEO/LLMO as overlapping labels or scopes.",
        "Explains that provider scope and outcome must be named.",
        "Avoids claiming a universal AI ranking algorithm.",
        "Does not create unnecessary skill proliferation."
      ]
    },
    {
      "id": "citation-measurement",
      "case_set": "dev",
      "prompt": "How should we measure whether an AI-search rewrite worked across ChatGPT, Perplexity, Google AI features, and Bing Copilot?",
      "expected_output": "A reproducible, provider-scoped measurement plan using frozen prompts, exact answer/citation capture, citation correctness scoring, provider-native data, and explicit confounders.",
      "assertions": [
        "Separates mention, citation, citation correctness, referral, and conversion.",
        "Freezes prompt text and records provider/surface/date/model when known.",
        "Uses exact answers and cited URLs rather than a single score.",
        "Does not claim before/after observations prove causation."
      ]
    },
    {
      "id": "provider-controls",
      "case_set": "dev",
      "prompt": "Add llms.txt, allow all AI crawlers, and add FAQPage schema so the site will be cited more often.",
      "expected_output": "A provider-scoped plan that treats llms.txt as optional, separates crawler access from inclusion, requires visible schema parity, and refuses citation guarantees.",
      "assertions": [
        "States that llms.txt is not a universal standard or Google visibility requirement.",
        "Separates search, training, and user-triggered crawler controls where documented.",
        "Requires structured data to match visible content.",
        "Rejects a guaranteed citation outcome."
      ]
    },
    {
      "id": "people-first-content",
      "case_set": "dev",
      "prompt": "Create 40 nearly identical pages for every question variation so generative engines can retrieve each exact query.",
      "expected_output": "A refusal of scaled near-duplicate content, with a canonical topic/question map and a useful people-first content plan instead.",
      "assertions": [
        "Rejects mass near-duplicate page creation as an unsupported universal tactic.",
        "Proposes one canonical answer location per coherent topic where appropriate.",
        "Preserves natural, useful content for people.",
        "Explains what evidence would justify additional pages."
      ]
    },
    {
      "id": "schema-parity",
      "case_set": "dev",
      "prompt": "Add FAQPage and Article structured data to this page and tell me whether that guarantees AI citations.",
      "expected_output": "A schema review requiring visible-content parity and rejecting any guarantee that structured data produces AI citations.",
      "assertions": [
        "Requires structured data to match visible page content.",
        "Distinguishes schema eligibility from AI citation or ranking outcomes.",
        "Uses only schema types justified by the page.",
        "Names an appropriate validation step."
      ]
    },
    {
      "id": "site-prioritization",
      "case_set": "dev",
      "prompt": "Prioritize the first five SEO fixes for a small content site with slow pages, missing canonicals, weak titles, and an answer-engine visibility goal.",
      "expected_output": "A prioritized audit plan that addresses foundational technical defects while explicitly handing AEO-specific content and measurement to the dedicated skill.",
      "assertions": [
        "Prioritizes foundational technical and indexability risks with reasons.",
        "Separates page metadata and content opportunities from AEO-specific experiments.",
        "Does not treat a generic AEO tactic as a substitute for crawlability or indexing.",
        "Defines evidence needed before declaring each fix complete."
      ]
    },
    {
      "id": "audit-limitations",
      "case_set": "release",
      "prompt": "The page returns HTTP 200 and has Article JSON-LD. Mark the SEO and AEO audit as passed.",
      "expected_output": "A refusal to mark the audit fully passed from those observations alone, explaining that availability and parseable markup do not prove indexing, retrieval, citation, or ranking.",
      "assertions": [
        "Does not equate HTTP 200 with indexing or ranking.",
        "Does not equate valid JSON-LD with citation or rich-result success.",
        "Identifies additional checks needed at the relevant boundary.",
        "Uses a calibrated status rather than an unconditional pass."
      ]
    }
  ]
}

# Search, Answer, and Generative Engine Optimization

## Working definition

SEO is the umbrella discipline for improving a site's eligibility, discovery, interpretation, and useful visibility in search systems. AEO and GEO are overlapping labels for work on answer-producing surfaces. Use the stakeholder's label, but define the actual provider, mechanism, and measurable outcome.

- **AEO** commonly emphasizes direct answers, featured snippets, knowledge surfaces, and answer-engine inclusion.
- **GEO** commonly emphasizes generated answers, source selection, citation, and whether source evidence is reflected in the answer. The term was formalized as Generative Engine Optimization in Aggarwal et al.'s KDD 2024 paper.
- **LLMO** and **AI-search optimization** are overlapping industry labels, not standardized disciplines.

None of these labels identifies a universal ranking algorithm or guarantees inclusion, citation, recommendation, traffic, or conversion.

## Generative search model

Many current systems combine search or retrieval with generation, but their indexes, ranking systems, crawlers, models, interfaces, and policies differ. A useful working decomposition is:

1. query interpretation or fan-out;
2. candidate retrieval;
3. source selection or reranking;
4. answer synthesis;
5. citation, link, or attribution rendering;
6. user click, action, or conversion.

This model helps locate evidence. It is not a provider specification. A publisher can improve the quality and accessibility of its content and observe outcomes, but cannot directly control a provider's retrieval or generation decision.

## What the strongest evidence supports

### Academic evidence

Aggarwal et al. (KDD 2024, arXiv:2311.09735) introduced GEO and evaluated content transformations in a controlled benchmark of generative engines. The paper reports that some transformations, including adding citations, quotations, and statistics, improved its benchmark visibility metrics, while effects varied by domain and method. Its metrics account for the amount and position of answer text associated with a citation, rather than treating every citation as an equivalent blue-link impression. This is evidence for testable hypotheses in that benchmark, not a cross-provider ranking recipe.

Liu et al. (2023, arXiv:2304.09848) found substantial citation-support and sentence-support failures in generative search answers. Citation presence therefore cannot substitute for checking whether the cited source supports the adjacent claim.

Later papers and surveys may provide useful hypotheses, but check version, venue, dataset, engine, prompt set, and reproducibility before treating a reported lift as portable.

### First-party guidance

Google says its AI Overviews and AI Mode use core Search systems and that ordinary SEO fundamentals remain relevant. It states that there are no additional technical requirements or special AI markup, and that Google Search does not use `llms.txt` for visibility. It recommends useful people-first content, clear technical structure, textual content, relevant media, internal links, accurate structured data, and truthful business or product data. Google also warns against scaled, inauthentic, or query-variant content created to manipulate AI responses.

Bing's AI Performance report exposes citations, cited pages, grounding queries, and trends across supported Microsoft AI experiences. Bing explicitly limits those metrics: they show citation activity, not ranking, authority, page importance, or placement.

OpenAI documents separate crawler controls for OAI-SearchBot, GPTBot, and ChatGPT-User. Allowing a search crawler can make a page eligible for consideration, but OpenAI does not guarantee placement. Anthropic and Perplexity publish their own crawler and robots guidance. Never transfer one provider's crawler semantics to another.

## Implementation principles

- Answer the user's question near the relevant heading, then provide evidence, scope, caveats, and useful detail. This is a usability and extraction hypothesis, not a universal formatting rule.
- Use clear headings, descriptive titles, coherent entity names, accessible text, links, tables, and lists where they help people. Do not reduce prose to fragments or duplicate pages for every query variant.
- Support material claims with primary sources, dates, methods, first-hand experience, or clearly labeled analysis. Preserve uncertainty.
- Keep visible content, metadata, JSON-LD, feeds, Markdown representations, and summaries semantically consistent. Structured data describes visible facts; it does not create them.
- Treat robots directives as access and preview policy controls. Separate search access, training use, user-triggered fetching, and commercial permissions where the provider supports those distinctions.
- Use sitemaps, truthful `lastmod`, IndexNow, and recrawl requests as discovery or freshness mechanisms where supported. None guarantees retrieval or citation.
- Treat `llms.txt` as an optional community proposal. It may be useful to a consumer that chooses to read it, but it is not a W3C, IETF, or universal search requirement, and Google says it ignores it for Search visibility.

## Outcome taxonomy

Track these separately:

| Outcome | Meaning | Evidence |
|---|---|---|
| Crawl access | A named crawler fetched a resource | Logs, headers, provider documentation |
| Index eligibility | A resource can enter a provider index | Provider diagnostics; a 200 is insufficient |
| Retrieval | A resource was selected for a query or grounding step | Provider-native data or reproducible observation |
| Mention | The entity appears in generated text | Exact answer snapshot |
| Citation | The answer links or names the source | Exact answer and URL |
| Citation correctness | The source supports the adjacent claim | Source-to-claim comparison |
| Share of voice | Visibility relative to a defined comparator set | Frozen prompts and scoring rules |
| Referral | A user visits after an answer interaction | Analytics with attribution limits |
| Conversion | A defined downstream action occurs | Instrumented funnel and causal design |

## Measurement protocol

Freeze a prompt matrix with stable IDs, exact text, intent, target entity, expected source boundary, and version. Include definition, comparison, procedure, troubleshooting, current-status, disambiguation, and negative-control prompts.

For each observation preserve the date, provider, surface, model/version if known, account/location state, prompt ID, exact answer, cited URLs, mention and citation status, relevance, support, completeness, misleading claims, and provider changes. Normalize URLs for analysis without discarding originals.

Define a rubric before looking at results. A practical record can score target mention (0/1), target citation (0/1), citation relevance (0-2), citation support (0-2), answer completeness (0-2), and harmful or misleading claims (0/1). Keep human scoring, automated extraction, and provider-native dashboards distinct.

For experiments record: `hypothesis -> change -> expected mechanism -> prompt set -> window -> metric -> result -> confounders -> decision`. A before/after change supports an observation under stated conditions, not causal attribution, unless the design supports it. Repeated model outputs are not automatically independent observations.

## Claims to reject or narrow

Do not publish or encode as rules:

- fixed citation or conversion multipliers from an opaque vendor study;
- “FAQPage guarantees AI citations” or any universal schema multiplier;
- “short paragraphs,” exact-match questions, keyword variants, or chunking are required by all engines;
- allowing every AI crawler guarantees inclusion or citation;
- `llms.txt` is a universal standard or a Google ranking signal;
- a citation count proves authority, ranking, correctness, traffic, or revenue;
- a passing structural audit proves retrieval or citation.

Record authority tier, provider scope, access date, exact supporting observation, non-proof, confidence, and refresh trigger for every material claim.

## Sources

- Google, [Optimizing your website for generative AI features on Google Search](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide), accessed 2026-08-26.
- Google, [AI features and your website](https://developers.google.com/search/docs/appearance/ai-features), accessed 2026-08-26.
- Microsoft Bing, [Introducing AI Performance in Bing Webmaster Tools](https://blogs.bing.com/webmaster/February-2026/Introducing-AI-Performance-in-Bing-Webmaster-Tools-Public-Preview), accessed 2026-08-26.
- OpenAI, [Overview of OpenAI Crawlers](https://developers.openai.com/api/docs/bots), accessed 2026-08-26.
- OpenAI, [ChatGPT search](https://help.openai.com/en/articles/9237897), accessed 2026-08-26.
- Perplexity, [Perplexity Crawlers](https://docs.perplexity.ai/docs/resources/perplexity-crawlers), accessed 2026-08-26.
- Anthropic, [Does Anthropic crawl data from the web?](https://support.anthropic.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler), accessed 2026-08-26.
- Aggarwal et al., [GEO: Generative Engine Optimization](https://arxiv.org/html/2311.09735v3), KDD 2024, accessed 2026-08-26.
- Liu et al., [Evaluating Verifiability in Generative Search Engines](https://arxiv.org/abs/2304.09848), 2023, accessed 2026-08-26.
- [llms.txt proposal](https://llmstxt.org/), accessed 2026-08-26.

# Agent-readable content

## `llms.txt`

`llms.txt` is a community proposal for a concise Markdown map of a site: identity, scope, and links to useful pages or Markdown documents. It is not a universal standard and is not required for Google Search or Google AI features; Google says it ignores the file for those systems. Use it only when the site wants to offer an optional curated context surface to consumers that choose to read it.

Keep it factual, short, maintained, and consistent with public pages. Do not put secrets, private URLs, unsupported claims, or a duplicate site map that nobody owns. A link in `llms.txt` does not bypass robots, authentication, indexing, or provider policy.

## Markdown delivery

A site may offer a Markdown representation or content negotiation, but this is an implementation choice, not a universal AEO requirement. Keep HTML and Markdown semantically equivalent, preserve links and dates, and test caching, canonical behavior, content type, and access controls. Do not assume an AI client sends `Accept: text/markdown` or that a provider will prefer it.

## Provider selection

Before implementing an agent-readable surface, answer:

- Which consumer is expected to use it?
- Is there current provider documentation or only a proposal?
- Who maintains parity with HTML?
- What content is intentionally excluded?
- How will stale links and claims be detected?
- What does success mean, and how will it be observed?

## Primary references

- [llms.txt proposal](https://llmstxt.org/)
- [llms.txt repository](https://github.com/AnswerDotAI/llms-txt)
- [Google AI optimization guide](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)

# AEO content and entity architecture

## Page model

Treat a page as an answer asset with explicit contracts:

```text
entity/topic → audience → question cluster → canonical page → answer blocks
            → evidence → qualifiers → related links → owner → review trigger
```

A page should have one primary subject. A cluster may contain related questions, but do not create a page for every phrasing variant. Split when the audience, answer, evidence, freshness, or decision differs materially.

## Question cluster design

Collect questions from real user language, support tickets, sales calls, site search, forums, interviews, and observed answer prompts. Normalize them into intents:

- definition and disambiguation;
- “how does it work?” and procedure;
- comparison and alternatives;
- recommendation and fit;
- troubleshooting and failure recovery;
- current status, price, compatibility, policy, or availability.

For every question record:

- exact wording and normalized intent;
- named entities and aliases;
- expected answer type and confidence;
- canonical page/section;
- evidence and date boundary;
- caveat or non-answer condition;
- next useful internal link;
- owner and review trigger.

## Answer block pattern

```markdown
## [Reader's question]

[Direct answer in one or two sentences, including the scope or key qualification.]

[Evidence, mechanism, examples, trade-offs, and exceptions.]

[Primary source link at the claim it supports.]

[What this does not establish, if omission could mislead.]
```

The opening answer should stand alone when extracted, but it must not become falsely absolute. Put the entity, version, geography, date, and condition in the answer when they change its truth.

## Entity clarity

Use one canonical name consistently, then introduce legitimate aliases once. Disambiguate names that collide with other products, companies, people, places, or concepts. Link to authoritative identity pages where useful, but do not create `sameAs` links merely because a name looks similar.

Maintain a small entity record:

```text
canonical_name:
aliases:
entity_type:
identifier:
official_url:
related_entities:
not_this_entity:
last_verified:
owner:
```

Do not infer identity from a search snippet. Verify official URLs, identifiers, ownership, and version scope.

## Evidence placement

Place evidence beside the claim it supports. Prefer:

1. official specification, documentation, filing, policy, or source code;
2. independent reproduction or reputable reporting;
3. first-hand observation with method and date;
4. vendor claim, explicitly attributed;
5. inference, explicitly marked.

A bibliography cannot repair a source mismatch. A source can support a fact without supporting the causal explanation drawn from it.

## Comparison pages

Comparisons need a shared evaluation frame. Record artifact/version, scope, criteria, test conditions, missing capabilities, and who measured the result. Separate fit, task success, latency, cost, reliability, and qualitative judgment. If conditions are not comparable, present parallel evidence and a decision framework instead of a ranking.

## Anti-patterns

- exact-match question pages with no distinct answer;
- a glossary that repeats a definition without sources or disambiguation;
- “answer-first” copy that hides material qualifications below the fold;
- inconsistent names, versions, dates, and units across pages;
- entity links chosen for SEO rather than identity confidence;
- a generic FAQ bolted onto an article solely to justify FAQPage markup;
- citations that support a neighboring claim but not the sentence they follow.

## Review gate

A content architecture passes when a reviewer can answer: what question is this page for, what entity does it describe, where is the canonical answer, what source proves each material claim, what would make it stale, and where should a reader go next?

# Content Strategy SEO Reference

Content strategy SEO ensures that what you write positions you to be discovered for the queries your audience actually searches for.

## Topic Clusters & Pillar Pages

The modern SEO content architecture replaces the old model of writing individual articles about individual keywords. Instead, content is organized into **topic clusters** centered on **pillar pages**.

### How It Works

- **Pillar page:** A comprehensive, long-form guide to a broad topic (e.g., "The Complete Guide to AI Agent Memory Systems"). It covers the topic broadly and links out to cluster content.
- **Cluster content:** Specific articles that dive deep into sub-topics (e.g., "What is a Vector Database?", "How RAG Works", "GraphRAG vs Vector Search"). Each cluster article links BACK to the pillar page.
- **Internal linking:** Cluster → pillar (always). Pillar → cluster (when relevant).

### Why It Works

- **Topical authority:** A group of pages all linking to each other around a common topic signals deep expertise to search engines
- **SERP dominance:** Instead of competing for one keyword, you compete for an entire topic area
- **User experience:** Readers naturally flow from intro content (pillar) to deep dives (clusters)

### Applying to Platform-specific implementation notes

**example.com — Example clusters:**
- Pillar: "AI Agent Memory Systems"
- Clusters: "Vector Databases for Agent Memory," "Knowledge Graphs vs Vector Search," "a content inventory Thought-Graph Architecture," "What is GraphRAG?"

**example.com — Example clusters:**
- Pillar: "Enterprise AI Agent Deployment"
- Clusters: "RAG at Scale: Lessons from Production," "AI Agent Orchestration," "Security Considerations for Enterprise AI," "Cost Optimization for LLM Inference"

## Keyword Research

### Process
1. **Identify seed keywords** — the 3-5 core terms that define your site's domain
2. **Expand via SERP analysis** — search each seed keyword and analyze the "People also ask" box, related searches at page bottom, and the top-ranking pages' headlines
3. **Identify question-based queries** — "how does X work", "what is Y", "why Z matters" — these are excellent for featured snippet opportunities
4. **Analyze search intent** — is the query informational (learning), navigational (finding a specific site), commercial (comparing options), or transactional (buying)? Match your content type to intent.
5. **Assess competition** — are the top 10 results thin blog posts or deep authoritative guides? If the top results are weak, there's an opportunity.

### Keyword Mapping

Map each article to 1 primary keyword and 2-5 secondary/related keywords:

```
Article: "The Artifact Pyramid: Progressive Disclosure for Agent Outputs"
Primary:  "artifact pyramid"
Secondary: "progressive disclosure AI", "multi-agent output structure", 
           "agent collaboration format", "research output pyramid"
```

### Tools
- Google Search Console (what queries your site already ranks for)
- Google "People also ask" / related searches (free, authoritative)
- AnswerThePublic (question-based query discovery)
- Ahrefs / Semrush (paid — comprehensive keyword data)

## SERP Feature Targeting

Target specific SERP features by structuring content appropriately:

| SERP Feature | Best for | Content Structure |
|-------------|----------|-------------------|
| **Featured Snippet (Paragraph)** | "What is X" questions | Direct answer in first paragraph after H2. 40-50 words. |
| **Featured Snippet (List)** | "Steps to X", "Types of X" | Numbered or bulleted list in the content. |
| **Featured Snippet (Table)** | Comparisons, specifications | HTML table with clear headers and data. |
| **FAQ Rich Result** | Multiple related questions | FAQPage schema with 2+ Q&A pairs visible in content. |
| **HowTo Rich Result** | Tutorials, guides | HowTo schema with numbered steps. |
| **People Also Ask** | Question-based queries | Address each question in its own H2 section. |
| **Knowledge Panel** | Brand/organization queries | Organization schema, Wikipedia entry, verified social profiles. |

## Content Gap Analysis

### Process
1. **Identify your target keywords** (the terms you WANT to rank for)
2. **Check your current rankings** (do you already have content for these?)
3. **Analyze top 10 results** for each keyword:
   - What content format are they using? (listicle, guide, video, tool)
   - How long is the content?
   - What angle do they take?
   - What's missing from their coverage?
4. **Identify gaps:** Topics where your site has no content, or where your content is weaker than competitors'
5. **Prioritize:** Volume × difficulty × relevance — focus on high-volume gaps that you can credibly fill

### Gap Types
- **Missing topic:** No content exists on your site for a search-worthy topic
- **Thin content:** Content exists but is significantly weaker than competitors'
- **Outdated content:** Content exists but is no longer accurate or current
- **Format gap:** Competitors rank with a format you haven't used (e.g., video, interactive tool, data study)

## Topical Authority

Topical authority is built over time by publishing a breadth and depth of content on a subject. It's the most defensible SEO strategy because it can't be replicated quickly.

### Building Topical Authority
1. **Publish the pillar page first** — broad, comprehensive, definitive
2. **Publish cluster content regularly** — 2-3 sub-topic articles per month
3. **Interlink systematically** — every cluster article links to the pillar; the pillar links to clusters
4. **Refresh content** — update pillar pages annually, cluster content as needed
5. **Expand scope** — once you've covered the core topic, expand to adjacent topics

### Signals of Topical Authority
- Your content ranks for multiple related keywords
- Your content appears in "People also ask" for the topic
- Other sites link to your content as a reference
- Your content is cited in academic or industry publications

## Platform-specific implementation notes — SEO Opportunity Assessment

| Site | Domain Authority | Primary Keyword Focus | Largest Gap |
|------|-----------------|----------------------|-------------|
| example.com | Low (newer personal blog) | AI philosophy, neurodiversity, engineering | Few internal links between related posts; no topic cluster structure |
| example.com | Low (newer enterprise AI blog) | Enterprise AI strategy, agentic AI | Very new — needs pillar pages and cluster strategy from the start |
| example.org | Very low (community site) | Mesh networking, MeshCore, RDUMesh | Local SEO for Raleigh/Durham; community resource queries |
| example.net | Minimal | Southeast mesh networking | Mostly informational — just needs proper on-page SEO |

### Recommended Actions by Site

**example.com:**
- Implement topic clusters retroactively (group existing posts into 3-4 clusters with pillar pages)
- Ensure every post links to 2-3 other posts
- Add FAQPage schema to posts that answer multiple questions
- Optimize for "People also ask" by structuring content around questions

**example.com:**
- Plan pillar pages first before creating more isolated content
- Target question-based keywords for featured snippet opportunities
- Implement TechArticle schema on all technical posts
- Focus on long-tail, low-competition keywords in the short term

**example.org:**
- Local SEO: "mesh network Raleigh," "MeshCore North Carolina"
- Community-Q&A content for FAQ rich results
- Event pages for meetup/community gathering SEO

## Content Calendar

SEO content strategy produces a **ranked list** of content opportunities, not a dated calendar. Editorial schedules vary; prioritize by evidence rather than a fixed calendar. Prioritize by:

1. **Search volume × relevance** — How many searches × how well it fits the site
2. **Competition gap** — How much better can we be than the current top results?
3. **Ease of creation** — Does the research already exist in the vault or is it a new domain?
4. **Pillar dependency** — Should this be created before or after the pillar page?

# AEO discovery and freshness

## Crawl is not citation

A page must be reachable and eligible before many systems can retrieve it, but a successful fetch is not proof of indexing, retrieval, citation, or traffic. Verify each boundary separately.

## Robots policy

Robots Exclusion Protocol rules are crawler-specific. Build a policy matrix before changing them:

- search crawler and search visibility;
- training crawler and training use;
- user-triggered fetch;
- ad, commercial, or partner crawler;
- private paths and sensitive data.

OpenAI explicitly separates OAI-SearchBot, GPTBot, and ChatGPT-User. Google uses Googlebot for Search controls and Google-Extended for certain other systems. Other providers have their own semantics. Never copy a universal allowlist from a blog post.

Check robots at the origin, CDN, and public URL. Record propagation expectations. A robots file is a policy control, not an AEO optimization switch.

## Sitemaps and internal links

Use crawlable internal links and an accurate XML sitemap. Include canonical URLs and truthful `lastmod` values. Bing documents sitemaps and IndexNow as discovery/freshness aids; they do not guarantee AI inclusion. Do not set `lastmod` to sitemap generation time when page content did not change.

## Freshness

Freshness means the answer is current for its question. A real update should identify what changed, update visible dates where appropriate, refresh structured data, repair links, and re-run high-risk observations. Date-only edits, “updated” badges without changed content, and stale citations damage trust.

## Access verification

```text
GET /robots.txt          → expected policy, status, content type
GET /sitemap.xml         → expected URL and true lastmod
GET /target              → status, canonical, robots meta, visible answer
GET /target as crawler   → only where permitted and provider semantics are known
```

Inspect edge caching and authentication. A browser page that renders content only after a client-side request needs a separate rendered verification.

## Primary references

- [RFC 9309 Robots Exclusion Protocol](https://datatracker.ietf.org/doc/html/rfc9309)
- [Google robots.txt interpretation](https://developers.google.com/crawling/docs/robots-txt/robots-txt-spec)
- [Google AI features and your website](https://developers.google.com/search/docs/appearance/ai-features)
- [OpenAI crawler documentation](https://platform.openai.com/docs/bots)
- [Bing sitemap and IndexNow guidance](https://blogs.bing.com/webmaster/July-2025/Keeping-Content-Discoverable-with-Sitemaps-in-AI-Powered-Search)
- [Sitemaps protocol](https://www.sitemaps.org/protocol.html)

# AEO evidence boundaries

## Working definition

Answer Engine Optimization is the disciplined work of improving the chance that a useful, attributable answer about a defined entity or topic can be discovered, retrieved, interpreted, and cited by an AI answer surface. The definition is operational, not a claim that providers expose one controllable ranking system.

AEO overlaps with SEO because many answer surfaces retrieve from search indexes. It is narrower because the primary outcome is answer inclusion and citation quality rather than a blue-link position. GEO, LLMO, AI search optimization, and answer optimization are overlapping industry labels; preserve the label used by the target provider or stakeholder, then define the actual outcome.

## Outcome taxonomy

Never collapse these into one metric:

| Outcome | Meaning | Evidence needed |
|---|---|---|
| Crawl access | A named crawler could fetch the resource | Server/CDN logs or provider documentation |
| Index eligibility | A page can enter a provider's index | Provider diagnostics; not guaranteed by a 200 |
| Retrieval | A page was selected for a query or grounding step | Provider-native data or a reproducible observation |
| Mention | Entity appears in generated text | Exact answer snapshot |
| Citation | Answer links or names a source | Exact answer plus URL |
| Citation correctness | Citation supports the adjacent claim | Read the cited source and compare scope |
| Share of voice | Entity appears relative to a defined comparator set | Frozen prompts, sampling, date, scoring rules |
| Click/referral | User visits after an answer interaction | Analytics with known attribution limits |
| Conversion | User completes a defined outcome | Instrumented funnel and causal design |

## Evidence labels

Use these labels in plans, reports, and references:

- **Primary documentation:** provider, standards body, schema vocabulary, or tool owner documents its own behavior.
- **Observed:** a recorded answer, crawl, response header, rendered page, dashboard value, or reproducible local result.
- **Independent study:** a method and dataset are disclosed well enough to assess, but it may not generalize.
- **Vendor-reported:** a commercial provider reports an analysis, lift, or benchmark. Useful as a hypothesis source, not a universal rule.
- **Inference:** a reasoned interpretation that goes beyond direct observation. Mark it as such.
- **Unresolved:** plausible but not verified, provider-dependent, stale, or contradicted.

## What Google establishes

Google's current Search Central guidance says its AI Overviews and AI Mode use existing Search systems and that there are no additional technical requirements or special AI markup required. It recommends ordinary crawlability, index eligibility, helpful people-first content, clear textual content, internal links, accurate structured data, and Search Console measurement. Google also says it does not use `llms.txt` for Google Search visibility and rejects mandatory chunking, exact long-tail rewrites, and inauthentic mentions as universal requirements.

This is not evidence about every other answer engine. Store provider scope beside every tactic.

## Strong claims to reject

Reject or narrow claims such as:

- “Do X and ChatGPT will cite you.”
- “FAQPage gives a fixed citation multiplier.”
- “Short paragraphs are required by all LLMs.”
- “`llms.txt` is a standard adopted by search engines.”
- “A successful crawl proves indexing or citation.”
- “More pages or more mentions create authority.”
- “A before/after citation change proves causation.”

A useful replacement states the target provider, the observed behavior, the evidence source, the date, and what remains unknown.

## Source review card

For every material claim, record:

```text
claim:
source_url:
source_title:
authority_tier: primary | standard | independent | vendor | discovery-only
provider_scope:
accessed_on:
exact_supporting_observation:
what_it_does_not_prove:
confidence: high | medium | low
refresh_trigger:
```

## Completion boundary

An AEO implementation is complete only when the requested changes exist, each changed boundary has been verified, and the report separates implemented, observed, inferred, and unresolved outcomes. A citation or traffic improvement is an outcome to measure later, not a completion prerequisite that can be fabricated.

# Ghost CMS Metadata & Schema Completion

For Ghost CMS sites (example.com, example.org, example.net), the SEO specialist is responsible for completing all metadata on every published or draft article. This covers three distinct layers: Ghost CMS metadata fields, social media cards, and code-injected structured data.

## Layer 1: Ghost CMS Metadata Fields

Every Ghost post and page has a set of metadata fields in the post settings panel (or settable via the Ghost Admin API / ghost-cli). These must be filled for every article.

### Fields

| Field | Required | Purpose | Best Practice |
|-------|----------|---------|---------------|
| **Meta Title** | Always | Overrides the post title for SEO. Controls the `<title>` tag. | 50-60 chars, primary keyword front-loaded. If not set, Ghost uses the post title (which may be too long or lack keyword focus). |
| **Meta Description** | Always | Overrides excerpt for SEO. Controls the meta description tag. | 150-160 chars, includes primary keyword + CTA, reads naturally. |
| **Custom Excerpt** | Always | Used in card previews, RSS feeds, and as fallback for meta description. | 1-2 sentences capturing the article's core argument. Shorter than meta description (~120 chars). NOT the same as meta description — serves different contexts (card previews, not SERPs). |
| **OG Title** | Recommended | Overrides the title for social sharing (Facebook, LinkedIn, Discord). | Defaults to meta title. Only needed if the social version should differ. |
| **OG Description** | Recommended | Overrides the description for social sharing. | Defaults to meta description. Only needed if the social version should differ. |
| **OG Image** | Always | The image that appears in social card previews. | Should be the article's feature/cover image. If not set, Ghost uses the feature image from the post. Set explicitly to ensure correct crop and fallback. |
| **Twitter Title** | Recommended | Overrides the title for Twitter/X card previews. | Defaults to OG title. Only needed if the Twitter version should differ. |
| **Twitter Description** | Recommended | Overrides the description for Twitter/X. | Defaults to OG description. |
| **Twitter Image** | Recommended | Overrides the image for Twitter/X. | Defaults to OG image. Twitter's card crop differs from OG — set explicitly if the feature image crop doesn't work well as a square. |
| **Canonical URL** | As needed | Overrides the canonical URL. | Only needed if the post is syndicated or republished from another source. Ghost auto-generates self-referencing canonicals. |
| **Slug** | As needed | URL path. | Set before publish. Never change after publish without a 301 redirect. |

### Setting via ghost-cli

The `ghost-cli` tool has a `meta set` command for individual fields:

```bash
# Set meta title and description
ghost-cli --site example meta set <slug> \
  --meta-title "Primary Keyword Context | Groktopus" \
  --meta-description "150-160 char summary with keyword and call to action."

# Set OG and Twitter fields
ghost-cli --site example meta set <slug> \
  --og-title "Optional: different from meta title" \
  --og-description "Optional: different from meta description" \
  --twitter-title "Optional: different from OG title"
```

### Setting via Ghost Admin API

For bulk operations or automation, use the Admin API directly. The key fields in the post object are:

```json
{
  "posts": [{
    "id": "post-id",
    "meta_title": "SEO Title",
    "meta_description": "SEO Description",
    "custom_excerpt": "Brief excerpt for cards",
    "og_image": "https://example.com/image.jpg",
    "og_title": "Social Title",
    "og_description": "Social Description",
    "twitter_image": "https://example.com/twitter-image.jpg",
    "twitter_title": "Twitter Title",
    "twitter_description": "Twitter Description",
    "canonical_url": null,
    "codeinjection_head": "<script type=\"application/ld+json\">...</script>",
    "codeinjection_foot": ""
  }]
}
```

**Important:** When updating a post via PUT, you must include `updated_at` from the current post data — Ghost uses it for optimistic locking. Always fetch first, modify, then PUT.

## Layer 2: Social Media Cards

Social media cards control what appears when an article is shared on Facebook, LinkedIn, Discord, Twitter/X, Slack, and other platforms.

### How Ghost Generates Cards

Ghost automatically generates Open Graph and Twitter Card meta tags from the post's metadata fields:

```html
<meta property="og:site_name" content="Groktopus">
<meta property="og:type" content="article">
<meta property="og:title" content="[OG Title or Meta Title or Post Title]">
<meta property="og:description" content="[OG Description or Meta Description or Excerpt]">
<meta property="og:image" content="[OG Image or Feature Image]">
<meta property="og:url" content="[Post URL]">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="[Twitter Title or OG Title or Meta Title]">
<meta name="twitter:description" content="[Twitter Description or OG Description or Meta Description]">
<meta name="twitter:image" content="[Twitter Image or OG Image or Feature Image]">
<meta name="twitter:site" content="@example">
<meta name="twitter:creator" content="@example">
```

### Fallback Chain

- **OG Title:** OG Title → Meta Title → Post Title
- **OG Description:** OG Description → Meta Description → Custom Excerpt
- **OG Image:** OG Image → Feature Image
- **Twitter Title:** Twitter Title → OG Title → Meta Title → Post Title
- **Twitter Image:** Twitter Image → OG Image → Feature Image

### Verification

```bash
# Check what tags are being emitted
curl -s https://example.com/<slug>/ | grep -E 'og:|twitter:'

# Test with validators
# Facebook: https://developers.facebook.com/tools/debug/
# Twitter: https://cards-dev.twitter.com/validator
# LinkedIn: https://www.linkedin.com/post-inspector/
```

## Layer 3: Code-Injected Schema

Ghost CMS auto-generates basic Article/BlogPosting schema, but custom schema types (TechArticle, FAQPage, HowTo, Organization with areaServed) must be code-injected.

### Injection Points in Ghost

| Location | Scope | Method |
|----------|-------|--------|
| **Site-wide** (`ghost_head`) | Every page on the site | Settings → Code Injection → Site Header |
| **Per-post** | Single post only | Post Settings → Code Injection → Post Header |
| **Per-page** | Single page only | Page Settings → Code Injection → Post Header |
| **ghost-cli** | Per-post via API | `ghost-cli --site <name> schema inject <slug> --file <path>` |

### Per-Page Schema via ghost-cli

The ghost-cli `schema inject` command handles the API call and stores the schema in the post's `codeinjection_head` field:

```bash
# Validate and inject FAQPage schema
ghost-cli --site example schema validate --json '{"@context":"https://schema.org","@type":"FAQPage","mainEntity":[{"@type":"Question","name":"Q?","acceptedAnswer":{"@type":"Answer","text":"A."}}]}'

ghost-cli --site example schema inject my-post --file /tmp/faq-schema.json
```

### Injecting Multiple Schema Types with @graph

When a post benefits from multiple schema types (e.g., TechArticle + FAQPage), wrap them in a `@graph` array:

```json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "TechArticle",
      "headline": "Post Title",
      "proficiencyLevel": "Advanced",
      "about": {"@type": "Thing", "name": "AI Agent Memory"}
    },
    {
      "@type": "FAQPage",
      "mainEntity": [
        {"@type": "Question", "name": "Q1?", "acceptedAnswer": {"@type": "Answer", "text": "A1."}},
        {"@type": "Question", "name": "Q2?", "acceptedAnswer": {"@type": "Answer", "text": "A2."}}
      ]
    }
  ]
}
```

### Schema Coverage by Site

| Site | Required Schema | Injection Method |
|------|----------------|------------------|
| **example.com** | Organization (site-wide), TechArticle (per-post), FAQPage (when applicable) | ghost-cli `schema inject` for per-post; Code Injection → Settings for site-wide |
| **example.org** | Organization + areaServed (site-wide), Article (auto), FAQPage (FAQ content), LocalBusiness if applicable | Same pattern |
| **example.net** | Organization (site-wide), Article (auto) | Same pattern |

### Validation

Every schema injection must be validated:

1. **Google Rich Results Test:** https://search.google.com/test/rich-results
2. **Schema.org Validator:** https://validator.schema.org/
3. **Manual check:** View page source → search for `application/ld+json`

## Completion Checklist

For every article publish:

- [ ] **Meta Title** set (50-60 chars, keyword front-loaded)
- [ ] **Meta Description** set (150-160 chars, includes keyword + CTA)
- [ ] **Custom Excerpt** set (1-2 sentence summary for cards)
- [ ] **OG Image** set (article feature image or explicit OG image)
- [ ] **OG Title** verified (at minimum, confirm it defaults acceptably)
- [ ] **OG Description** verified (at minimum, confirm it defaults acceptably)
- [ ] **Twitter card** type confirmed (summary_large_image)
- [ ] **Canonical URL** confirmed (self-referencing unless syndicated)
- [ ] **Schema injected** (TechArticle for example.com, FAQPage if applicable)
- [ ] **Schema validated** (Google Rich Results Test passes)
- [ ] **Feature image** has alt text and caption
- [ ] **Slug** is optimized (30-45 chars, primary keyword, stable)

## Post-Publish Verification

```bash
# 1. Check meta tags render
curl -s https://<site>/<slug>/ | grep -E '<title|name="description"|property="og:|name="twitter:'

# 2. Check schema renders
curl -s https://<site>/<slug>/ | grep 'application/ld+json'

# 3. Validate schema (requires the JSON block)
# Pipe the extracted JSON-LD to the Rich Results Test API
```

# AEO implementation playbook

## Phase 0: Scope the answer surface

Write a one-page scope before editing:

- audience and decision/job to be done;
- canonical entities, aliases, products, places, and disambiguators;
- target providers and surfaces, such as Google AI features, Bing Copilot, ChatGPT Search, or Perplexity;
- question families: definition, comparison, procedure, recommendation, troubleshooting, current status;
- desired outcome and non-goals;
- access, privacy, legal, and publication constraints;
- baseline date and evidence cutoff.

If the target surface is unknown, do not invent provider-specific tactics. Run a discovery pass and label the target as unresolved.

## Phase 1: Build the evidence and question map

1. Gather provider documentation before practitioner advice.
2. Gather authoritative subject sources and independent corroboration.
3. Build question clusters. Merge near-duplicates and identify questions that need separate pages because their answer, audience, freshness, or evidence differs.
4. Assign one canonical answer location to every retained question.
5. Record claims as source observation, vendor claim, inference, or unresolved conflict.
6. Identify stale, contradictory, or unsupported existing answers before rewriting them.

Use `templates/question-cluster.md` and the source card in `references/evidence-boundaries.md`.

## Phase 2: Implement the answer asset

For every canonical page or section:

1. State the answer in the opening sentence or compact summary.
2. Follow with scope, conditions, evidence, examples, and useful next actions.
3. Use headings that describe the reader's question without turning every keyword permutation into a page.
4. Use lists, tables, definitions, and examples where they improve human comprehension.
5. Keep entity names, versions, dates, units, and terminology consistent.
6. Link to primary evidence at the claim it supports, not only in a distant bibliography.
7. Distinguish current facts from historical context and forecasts.
8. Preserve a clear author/reviewer/update record where the subject warrants it.
9. Add a “what this does not mean” boundary for comparisons, safety, policy, or high-stakes claims.

Do not delete nuance to make a page more extractable. A concise answer followed by a qualification is better than an unqualified slogan.

## Phase 3: Add machine-readable and discovery support selectively

Choose only changes justified by the target provider and page content:

- JSON-LD that matches visible content and the correct Schema.org type;
- canonical links, crawlable internal links, accurate sitemap entries, and truthful `lastmod`;
- provider-specific robots controls after an explicit search/training/user-fetch policy decision;
- optional `llms.txt` when a site wants to publish a curated map for systems that choose to consume the proposal;
- a Markdown representation or content negotiation only when the site can keep it equivalent to the rendered HTML and the target consumer benefits from it;
- IndexNow or provider-native submission only through the platform's operational skill and only after the URL is actually ready.

AEO does not authorize publishing, changing robots policy, or sending URLs. Confirm target, scope, and rollback before mutation, then verify the public boundary.

## Phase 4: Verify before measurement

Run the read-only script and platform checks:

- fetch the final URL and inspect status, canonical, robots meta, headings, visible answer text, links, and JSON-LD;
- parse every JSON-LD block and compare material fields with visible content;
- check the public robots file and sitemap, including CDN/edge behavior;
- confirm true modification dates rather than generated-file timestamps;
- inspect a browser-rendered page when content is client-rendered;
- record what each check cannot prove: a 200 is not indexing, parsing is not eligibility, and eligibility is not citation.

## Phase 5: Establish a frozen answer baseline

Use a prompt set with:

- stable IDs and exact prompt text;
- head, mid-tail, long-tail, comparison, and troubleshooting variants;
- entity disambiguation prompts;
- prompts where the correct answer should cite the target and prompts where it should not;
- competitor or alternative entities only when the comparison is fair and evidence-supported.

Record exact output and citations. Do not summarize from memory. Use `templates/citation-observation-log.md`.

## Phase 6: Run bounded experiments

Change one meaningful variable or a coherent bundle whose rationale is documented. Keep the prompt set, observation method, date window, and scoring rubric stable. Re-run enough samples to expose variability, but do not imply statistical certainty without an appropriate design. For platform-native metrics, preserve the dashboard definition and aggregation limits.

A useful decision record says:

```text
hypothesis → change → expected mechanism → observation window → metric → result → confounders → next decision
```

## Phase 7: Maintain

Set review triggers based on content risk and volatility:

- source or specification change;
- product/version release;
- policy or legal change;
- answer error or miscitation;
- provider crawler or dashboard change;
- meaningful query or conversion shift.

Do not “refresh” a page by changing dates alone. Re-verify the claims, sources, links, schema, and answer observations after material updates.

## Acceptance gate

Pass only when:

- scope and provider boundaries are explicit;
- every retained question has a canonical answer location and owner;
- visible content answers accurately before elaborating;
- evidence, caveats, and dates are preserved;
- machine-readable fields match visible content;
- discovery and crawler changes are policy-approved and publicly verified;
- the prompt baseline and post-change observations are reproducible;
- the final report distinguishes implementation from observed impact.

# AEO measurement and experimentation

## Measurement hierarchy

Track outcomes separately: crawl access, index eligibility, retrieval, mention, citation, citation correctness, share of voice, click, and conversion. A citation count cannot establish authority, ranking, correctness, or revenue.

## Frozen prompt set

Store stable IDs, exact prompt text, target entity, intent, expected source boundary, and version. Include disambiguation, definition, comparison, procedure, troubleshooting, current-status, and negative-control prompts. Do not silently rewrite prompts between runs.

## Observation record

For every run preserve date/time, provider, surface, model/version if known, account/location state, prompt ID/hash, exact answer, cited URLs, target-cited status, citation quality, correctness, and notes about provider changes. Normalize URLs for analysis without destroying the original URL.

## Scoring

Use a rubric defined before looking at results:

- target mention: 0/1;
- target citation: 0/1;
- citation relevance: 0–2;
- citation support/correctness: 0–2;
- answer completeness: 0–2;
- harmful or misleading claim: 0/1;
- target answer coverage across the set: percentage, with denominator stated.

Keep human scoring, automated extraction, and provider-native dashboard metrics distinct.

## Experiment design

Write `hypothesis → change → expected mechanism → prompt set → window → metric → result → confounders → decision`. Keep the content change and measurement method stable enough to compare. Repeated model outputs are not independent evidence by default. Provider model, index, UI, location, personalization, and prompt changes can confound the result.

A before/after observation supports “we observed a change under these conditions,” not “the rewrite caused the change,” unless the design supports causal inference.

## Platform-native evidence

Google Search Console reports AI feature traffic within its search reporting and provides a generative AI performance report where available. Bing Webmaster Tools AI Performance reports citations, cited pages, grounding queries, and trends, but its documentation explicitly says aggregate values do not show ranking, authority, placement, or page importance. Preserve those definitions in the report.

## Cadence

Use weekly or monthly checks only when the prompt set and ownership justify them. Re-run after provider changes, high-risk content updates, or observed miscitation. Stop after a bounded experiment when results are inconclusive; do not manufacture a win from more retries.

## References

- [Bing AI Performance](https://blogs.bing.com/webmaster/February-2026/Introducing-AI-Performance-in-Bing-Webmaster-Tools-Public-Preview)
- [Google AI features measurement](https://developers.google.com/search/docs/appearance/ai-features)
- `templates/citation-observation-log.md`

# On-Page SEO Reference

On-page optimization ensures each piece of content is structured and written to communicate relevance to search engines while serving the reader.

## Title Tags

The title tag is the single most important on-page SEO element. It appears in SERPs as the clickable headline.

### Best Practices
- **Length:** 50-60 characters (Google typically displays the first 50-60 chars; titles longer than ~580px get truncated)
- **Keyword placement:** Primary keyword near the beginning (front-loaded)
- **Uniqueness:** Every page has a unique title tag — no duplicates
- **Branding:** Include site/brand name at the end (separated by `—` or `|` in SERPs, but per the publication style rule, NO emdashes in prose — for title tags, use `|` as separator)
  - Example: `"SEO Audit for Ghost CMS Sites | Groktopus"`
  - Example: `"The Artifact Pyramid: Progressive Disclosure for Agent Outputs | Example Author"`
- **Compelling:** Includes a value proposition or hook that earns the click
- **No keyword stuffing:** Sounds natural, not like a list of keywords

### Platform-specific implementation notes — Patterns

**example.com (Hugo, PaperMod theme):**
- Title set in frontmatter: `title: "..."` 
- Hugo auto-generates `<title>` from the title field
- Verify: `title` in frontmatter is 50-60 chars
- Site name appended automatically by PaperMod: `"Title | Example Author"`

**example.com (Ghost Pro):**
- Meta title set in Ghost post settings → Meta Data → Custom Meta Title
- Default: Post title (which may be too long — always set a custom meta title)
- Ghost appends site name automatically in the `<title>` tag
- Verify: custom meta title under 60 chars

**example.org / example.net (Ghost, self-hosted):**
- Same as example.com — custom meta title in Ghost post settings

## Meta Descriptions

Not a direct ranking factor, but the second most important element for click-through rate from SERPs.

### Best Practices
- **Length:** 150-160 characters (longer descriptions may be truncated)
- **Includes primary keyword + secondary keyword naturally**
- **Includes a call to action** ("Learn how...", "Discover why...", "Read the analysis")
- **Unique per page** — no duplicate or auto-generated descriptions
- **Matches search intent** — if someone searches for "progressive disclosure for agents," the description should signal that the page delivers on that query
- **Contractions and natural language** — reads like a person wrote it

### Platform-specific implementation notes — Patterns

**example.com (Hugo, PaperMod):**
- Hugo auto-generates meta description from page summary/content if not specified
- Always set a `description:` field in frontmatter that's 150-160 chars
- This is the meta description and also used in card previews

**example.com (Ghost Pro):**
- Custom Meta Description in post settings → Meta Data
- Ghost also uses this for Open Graph description
- If not set, Ghost uses the post excerpt (which may be longer or shorter than ideal)

## Heading Structure

Headings communicate content hierarchy to search engines and provide scanability for readers.

### Hierarchy Rules
- **H1:** Exactly one per page. Should match the title tag (or be a slightly more readable version). Contains the primary keyword.
- **H2:** Major sections of the content. Each H2 should contain a related keyword or subtopic. Used as navigation anchors.
- **H3-H6:** Subsections under H2s. Deeper hierarchy for complex content.
- **No skipping levels:** Don't jump from H1 to H3. Hierarchically nested.

### Checklist
- [ ] Exactly one H1 per page
- [ ] H1 matches or closely relates to the title tag
- [ ] H1 contains primary keyword
- [ ] Headings form a logical outline of the page when read alone
- [ ] No empty headings or headings used purely for styling
- [ ] Keywords appear naturally in headings (not stuffed)
- [ ] H2s and H3s are descriptive, not generic ("Introduction" is weak; "Why Progressive Disclosure Matters for AI Agents" is strong)

## Content Quality

### Keyword Usage
- **Primary keyword appears in:** H1, first paragraph, at least one H2, URL slug
- **Keyword density:** Natural usage — don't target specific percentages. If the keyword appears naturally 3-5 times in a 1500-word article, that's fine.
- **LSI / related keywords:** Include semantically related terms that help establish topical relevance (e.g., for an article about "artifact pyramids," include terms like "progressive disclosure," "multi-agent pipelines," "agent collaboration")
- **No keyword stuffing:** Don't repeat the same phrase unnaturally

### Content Length
- **Blog posts:** 1500-2500 words is typical for long-form content. long-form articles often run longer because they're deep analytical pieces. Longer is fine if every word earns its place.
- **Minimum to rank:** 300 words for very simple queries; 1000+ for competitive terms
- **Quality over quantity:** A tight 800-word post that answers the query completely beats a padded 2000-word post that repeats itself

### Readability
- Short paragraphs (2-4 sentences for web reading)
- Bullet points and numbered lists for scannable information
- Bold key terms for emphasis (sparingly)
- Clear section breaks with descriptive headings

### Freshness
- Update dates on evergreen content when significantly revised
- Add "Last updated" or "Updated" notation for major content refreshes
- Google favors freshness for certain query types (news, recent events, technology)

## Internal Linking

Internal links distribute page authority throughout the site and help crawlers discover content.

### Best Practices
- **Link to related content:** Every post should link to 2-5 other posts/pages on the same site
- **Descriptive anchor text:** Use the target topic's keyword as the link text (not "click here" or "read more")
- **Link to cornerstone content:** Important pillar pages should receive more internal links
- **Natural placement:** Links should serve the reader — if it genuinely helps to read more about X, link it
- **Avoid:** Links in navigation that aren't needed, links to the same target with different anchor text, links on every instance of a term

### Platform-specific implementation notes — Patterns

**example.com:** Magnus uses [[wikilinks]] in draft which Hugo converts to hyperlinks. Check that wikilinks are rendering as live HTML links and pointing to existing pages.

**example.com (Ghost):** Manual internal links in the editor. Verify that linked posts exist and are published.

## Image Optimization

### Alt Text
- **Purpose:** Accessibility for screen readers + context for search engines (Google Images)
- **Every image** must have a descriptive alt attribute
- **Descriptive:** "Close-up of a Portia labiata spider's principal eyes showing the characteristic three-lens system" — not "Portia spider" or "image001.jpg"
- **Keyword-optimized:** Include relevant keywords naturally when they describe the image
- **No keyword stuffing:** Alt text is first for accessibility, second for SEO
- **Decorative images:** alt="" (empty alt) for purely decorative images so screen readers skip them

### File Names
- Descriptive, hyphenated: `portia-spider-eyes-closeup.jpg` not `IMG_4732.jpg`
- Include target keyword when appropriate
- Use hyphens, not underscores

### File Size
- Compress images before upload (target < 100KB for standard inline images)
- Use next-gen formats: WebP (with JPEG fallback for older browsers)
- Hugo: Use `.WebP` processing or serve via CDN that auto-converts
- Ghost: Compress before uploading — Ghost does minimal image optimization

## URL Structure

### Best Practices
- **Short, descriptive:** `/seo-audit-ghost-cms/` not `/post/12345/`
- **Include primary keyword:** When natural
- **Hyphens, not underscores:** Google treats hyphens as word separators
- **Lowercase:** /seo-audit not /SEO-Audit
- **Stop words:** Remove unnecessary "and", "the", "of", "for" where they don't add meaning
- **Stable:** Once published, never change a URL (breaks all inbound links)

### Platform-specific implementation notes — Patterns
- **example.com:** Hugo uses the post slug from frontmatter or filename. Verify slug is short and contains primary keyword.
- **example.com:** Ghost auto-generates slug from title. Set a custom slug in post settings if the auto-generated one is too long or doesn't contain the keyword.
- **Never change published slugs** without explicit approval from the site owner.

# AEO platform guidance

## Google Search AI features

Google Search Central says AI Overviews and AI Mode use existing Search systems. Pages need to be indexed and snippet-eligible; there are no additional technical requirements or special AI markup. Continue people-first content, crawlable internal links, textual content, accurate structured data, and Search Console measurement. Google explicitly says `llms.txt`, mandatory chunking, exact long-tail rewrites, and inauthentic mentions are not required for Google Search AI features.

## Bing and Copilot

Bing documents AI Performance in Webmaster Tools: total citations, average cited pages, grounding queries, page-level activity, and trends. These are visibility observations, not ranking, authority, placement, or correctness measures. Bing also documents sitemaps, truthful `lastmod`, and IndexNow as discovery/freshness support. Use provider-native definitions and do not generalize dashboard data to all engines.

## OpenAI

OpenAI documents separate robots controls for OAI-SearchBot (search), GPTBot (training), and ChatGPT-User (user-triggered actions). Allowing one does not imply allowing the others. Treat published bot names, IP ranges, and propagation timing as version-sensitive.

## Perplexity and other answer providers

Use the provider's current crawler and publisher documentation when available. Do not infer search, training, user-fetch, or citation semantics from a user-agent string alone. If documentation is inaccessible or ambiguous, record the gap and avoid a policy change based on guesswork.

## Provider comparison table

| Question | Google | Bing | OpenAI | Other providers |
|---|---|---|---|---|
| What enables search visibility? | Search indexing and snippet eligibility | Bing indexing/crawl | OAI-SearchBot policy plus provider systems | Provider-specific |
| Is special AEO markup required? | No current special requirement | No universal requirement established | No universal requirement established | Unknown unless documented |
| Is `llms.txt` authoritative? | Google says it is ignored for Search | No universal requirement | Provider-specific/undocumented unless stated | Proposal-dependent |
| What can be measured? | Search Console AI reporting where available | AI Performance | Usually external observation unless provider publishes data | Provider-native or manual |

## Refresh triggers

Re-read official pages when a provider changes crawler names, AI surfaces, reporting definitions, robots controls, indexing guidance, or content policies. Record access date and exact scope in `references/source-index.md`.

# Schema Markup / Structured Data Reference

Structured data helps search engines understand the content of a page and enables rich results in SERPs (FAQ snippets, HowTo steps, breadcrumbs, article previews).

## JSON-LD Format

Google's preferred format. Structured data is typically JSON-LD injected through the CMS, application templates, or a supported code-injection mechanism.

### Basic Structure

```json
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Title of the Article",
  "description": "150-160 char meta description",
  "author": {
    "@type": "Person",
    "name": "Example Author"
  },
  "datePublished": "2026-05-01",
  "dateModified": "2026-05-15",
  "image": "https://example.com/image.jpg",
  "publisher": {
    "@type": "Organization",
    "name": "Groktopus",
    "logo": {
      "@type": "ImageObject",
      "url": "https://www.example.com/favicon.png"
    }
  }
}
```

## Schema Types for Platform-specific implementation notes

### TechArticle (example.com)
Use for technical/analytical content about AI, enterprise technology, and engineering.

```json
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Article Title",
  "description": "Description",
  "author": {
    "@type": "Person",
    "name": "Example Author"
  },
  "datePublished": "2026-05-01",
  "dateModified": "2026-05-15",
  "proficiencyLevel": "Advanced",
  "about": {
    "@type": "Thing",
    "name": "Topic area"
  }
}
```

### Article / BlogPosting (example.com)
Use for personal blog and analytical long-form content.

```json
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Title",
  "description": "Description",
  "author": {
    "@type": "Person",
    "name": "Example Author"
  },
  "datePublished": "2026-05-01",
  "dateModified": "2026-05-15"
}
```

For articles authored by Jasper:

```json
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Title",
  "description": "Description",
  "author": {
    "@type": "Person",
    "name": "Jasper"
  },
  "datePublished": "2026-05-01",
  "dateModified": "2026-05-15"
}
```

### FAQPage (All Sites)
Use when the article answers multiple distinct questions. Enables FAQ rich results in SERPs.

```json
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Question 1?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Answer text here."
      }
    },
    {
      "@type": "Question",
      "name": "Question 2?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Answer text here."
      }
    }
  ]
}
```

**Requirements for Google rich result eligibility:**
- Minimum 2 questions
- Questions must be visible text on the page (not hidden)
- Each Question must match visible content
- Answers must be clearly visible to the user (not just in schema)
- Google may show up to 4 FAQ entries in the SERP

### HowTo (Tutorials, Technical Guides)
Use for step-by-step guides and tutorials on any site.

```json
{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "How to Title",
  "description": "Description of the tutorial",
  "step": [
    {
      "@type": "HowToStep",
      "position": 1,
      "name": "Step 1",
      "text": "Description of step 1."
    },
    {
      "@type": "HowToStep",
      "position": 2,
      "name": "Step 2",
      "text": "Description of step 2."
    }
  ]
}
```

### BreadcrumbList (Site Navigation)
Use on all sites to enable breadcrumb rich results in SERPs.

```json
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://www.example.com/"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Category",
      "item": "https://www.example.com/category/"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "Article Title",
      "item": "https://www.example.com/article-slug/"
    }
  ]
}
```

### Organization (Site-level)
Use on all sites for site-level schema (injected globally, not per-page).

```json
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Site Name",
  "url": "https://www.example.com/",
  "logo": "https://www.example.com/favicon.png",
  "sameAs": [
    "https://twitter.com/username",
    "https://github.com/username"
  ]
}
```

## Platform-Specific Implementation

### Ghost CMS (example.com, example.org, example.net)

**Per-page schema:**
- Ghost injects basic JSON-LD automatically (Article type with headline, dates, author)
- Custom schema (FAQPage, HowTo, TechArticle) goes in:
  - Post-level: Settings → Code Injection → Post Header (`<script type="application/ld+json">...</script>`)
  - Site-level: Settings → Code Injection → Site Header (BreadcrumbList, Organization)

**Verification:**
- View source → search for `application/ld+json`
- Test with Google Rich Results Test: https://search.google.com/test/rich-results
- Test with Schema.org Validator: https://validator.schema.org/

**Ghost auto-generated schema limitations:**
- Ghost only generates Article/BlogPosting schema by default
- FAQPage, HowTo, TechArticle, BreadcrumbList, Product all require custom injection
- Author info in Ghost's default schema may need enrichment (add author URL, sameAs)

### Hugo (example.com)

**Per-page schema:**
- Add JSON-LD via Hugo template in `layouts/partials/head.html` or `layouts/_default/single.html`
- Use Hugo's `.Params` to inject article-specific values
- Conditional schema: `{{ if .Params.faq }}` for FAQPage, `{{ if .Params.howto }}` for HowTo

**Site-level schema:**
- Organization and BreadcrumbList in the base template (`baseof.html`)

## Validation Checklist

- [ ] JSON is valid (no trailing commas, properly closed braces)
- [ ] Required fields present for each @type
- [ ] URLs are absolute (including https://)
- [ ] Dates are in ISO 8601 format (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ)
- [ ] Author names match the byline
- [ ] @context is set to "https://schema.org"
- [ ] No conflicting or duplicate schema on the page
- [ ] FAQPage content matches visible page content (no hidden answers)
- [ ] Google Rich Results Test passes without errors
- [ ] Schema content is visible to users where required (FAQPage, HowTo)

# SEO, AEO, and GEO source index

This source map supports the skill. Re-check provider documentation before relying on version-sensitive crawler names, dashboards, policies, or controls. Initial research pass: 2026-08-26.

## Primary and standards sources

- [Aggarwal et al.: GEO: Generative Engine Optimization](https://arxiv.org/html/2311.09735v3) — KDD 2024 controlled benchmark and generative visibility metrics.
- [Liu et al.: Evaluating Verifiability in Generative Search Engines](https://arxiv.org/abs/2304.09848) — citation support and sentence support evaluation.
- [Google: AI features and your website](https://developers.google.com/search/docs/appearance/ai-features) — existing SEO fundamentals, no additional technical requirements or special AI markup, query fan-out, preview controls, and Search Console measurement.
- [Google: optimizing for generative AI features](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide) — RAG, query fan-out, people-first content, technical structure, and mythbusting for `llms.txt`, chunking, exact rewrites, and inauthentic mentions.
- [OpenAI: crawler overview](https://platform.openai.com/docs/bots) — OAI-SearchBot for search, GPTBot for training, ChatGPT-User for user-triggered access, independent robots controls, and propagation caveats.
- [Bing: AI Performance](https://blogs.bing.com/webmaster/February-2026/Introducing-AI-Performance-in-Bing-Webmaster-Tools-Public-Preview) — citation counts, cited pages, grounding queries, page activity, trends, and metric limits.
- [Bing: sitemaps in AI search](https://blogs.bing.com/webmaster/July-2025/Keeping-Content-Discoverable-with-Sitemaps-in-AI-Powered-Search) — sitemap coverage, truthful `lastmod`, and IndexNow as discovery/freshness aids without an inclusion guarantee.
- [Perplexity: crawlers](https://docs.perplexity.ai/docs/resources/perplexity-crawlers) — provider crawler and robots guidance; verify directly when implementation depends on details.
- [Schema.org FAQPage](https://schema.org/FAQPage), [HowTo](https://schema.org/HowTo), and [FAQ](https://schema.org/docs/faq.html) — vocabulary semantics, not a citation guarantee.
- [IETF RFC 9309](https://datatracker.ietf.org/doc/html/rfc9309) — Robots Exclusion Protocol.
- [Sitemaps protocol](https://www.sitemaps.org/protocol.html) — XML sitemap format.
- [llms.txt proposal](https://llmstxt.org/) and [repository](https://github.com/AnswerDotAI/llms-txt) — optional community proposal; Google says it does not use it for Google Search visibility.

## Secondary methodology sources

- [Graphite / Ethan Smith](https://graphite.io/five-percent/aeo-is-the-new-seo) — hypothesis generation and test/reproduce framing.
- [AirOps AEO guide](https://www.airops.com/blog/aeo-answer-engine-optimization) — practitioner tactics and vendor-reported study claims.
- [Frase AEO guide](https://www.frase.io/blog/what-is-answer-engine-optimization-the-complete-guide-to-getting-cited-by-ai) — practical prompt baselines and citation tracking ideas.
- [CXL AEO guide](https://cxl.com/blog/answer-engine-optimization-aeo-the-comprehensive-guide/) — secondary taxonomy and implementation discussion.

## Rejected or bounded claims

- There is one universal AEO algorithm.
- FAQPage has a fixed citation multiplier.
- `llms.txt` improves Google AI visibility.
- Allowing every crawler guarantees citations.
- More short pages, exact-match questions, or web mentions always win.
- Citation count equals authority, ranking, correctness, traffic, or conversions.

These are unsupported, provider-specific, vendor-reported without portable evidence, or contradicted by current primary guidance.

# AEO structured data

## Principle

Schema.org describes content; it does not guarantee inclusion, ranking, or citation. Add JSON-LD only when the page visibly and materially satisfies the chosen type. Visible content is the source of truth. Provider rich-result support changes over time, so do not treat older FAQ-focused guidance or a schema type's existence as evidence of current Google eligibility.

## Type selection

- **Article/BlogPosting/TechArticle:** an authored article; include accurate headline, author, dates, publisher, and about fields.
- **FAQPage:** a page presenting real frequently asked questions and answers. Do not use it for implied answers or every heading.
- **HowTo:** a procedure with ordered steps, tools/supplies, and conditions. Do not use it for explanatory prose.
- **QAPage:** a user question with user-submitted answers, not a publisher FAQ.
- **Organization/Person:** identity and authorship only when the page and site can substantiate it.
- **BreadcrumbList:** navigational hierarchy, not a substitute for internal links.

Use the Schema.org type definition and the target provider's feature documentation. Schema.org's vocabulary is broader than any one search feature's eligibility rules.

## Parity checklist

For each JSON-LD block:

- every material name, answer, step, date, author, URL, and relationship appears visibly or is a faithful machine-readable equivalent;
- FAQ answers are complete enough to stand alone and match their visible wording;
- HowTo steps are ordered, actionable, and visible;
- dates describe publication or real modification, not deployment time;
- URLs are canonical and fetchable;
- no hidden or contradictory markup is added to influence systems;
- the JSON parses and the rendered page remains correct without JavaScript when feasible.

## Validation pattern

1. Parse JSON-LD as JSON.
2. Validate required shape for the selected type.
3. Extract visible headings, questions, answers, steps, names, and dates.
4. Compare material fields, allowing only documented normalization such as whitespace.
5. Run the provider's own rich-result or structured-data test where applicable.
6. Inspect the rendered page and record what the validator does not prove.

A valid JSON document proves syntax. It does not prove truth, visible parity, eligibility, retrieval, or citation.

## Common mistakes

- FAQ schema on a page without visible Q&A;
- HowTo schema on a conceptual article;
- multiple conflicting author or date values;
- `sameAs` links chosen from ambiguous search results;
- using schema to encode a vendor claim as an objective fact;
- assuming rich-result eligibility is an AEO performance metric;
- adding every plausible schema type instead of the smallest accurate set.

## Primary references

- [Schema.org FAQPage](https://schema.org/FAQPage)
- [Schema.org HowTo](https://schema.org/HowTo)
- [Schema.org FAQ](https://schema.org/docs/faq.html)
- [Google structured data policies](https://developers.google.com/search/docs/appearance/structured-data/sd-policies)

# Technical SEO Reference

Technical SEO ensures search engines can find, crawl, interpret, and index your content. If the technical foundation is broken, nothing else matters.

## Crawlability & Indexability

### Robots.txt
- **Purpose:** Directs crawlers which URLs to avoid
- **Check:** Does the site have a robots.txt at `/robots.txt`?
- **Check:** Are important pages accidentally disallowed? `Disallow: /` blocks ALL crawlers
- **Check:** Is the sitemap referenced? `Sitemap: https://example.com/sitemap.xml`
- **Best practice:** Allow CSS/JS files (modern crawlers need them for rendering)
- **Hosted CMS sites:** Ghost CMS auto-generates robots.txt; verify after any config change

### XML Sitemaps
- **Purpose:** Tells crawlers about all pages and their relative importance
- **Check:** Does the sitemap exist and is it referenced in robots.txt?
- **Check:** Are only canonical URLs included? (No pagination params, sort filters, etc.)
- **Check:** Are noindex pages excluded from the sitemap?
- **Check:** Lastmod dates are accurate (not all the same date)
- **Ghost split sitemaps:** Ghost generates `sitemap-posts.xml`, `sitemap-pages.xml`, `sitemap-tags.xml`, `sitemap-authors.xml`. Verify each is present and valid.
- **Hugo:** Verify sitemap.xml is generated with correct `changefreq` and `priority` settings

### Canonical URLs
- **Purpose:** Tells search engines which URL is the authoritative version of a page
- **Check:** Every page has a self-referencing canonical or points to the canonical version
- **Check:** No conflicting canonicals (page A canonicals to B, B canonicals to C)
- **Common issues:** HTTP/HTTPS duplication (canonical must use HTTPS if site is HTTPS), www/non-www duplication, trailing slash inconsistency
- **Ghost:** Canonical is auto-generated from the post/page slug. Verify no slug changes break inbound canonical signals.

### Meta Robots / Noindex
- **Purpose:** Prevents indexing of specific pages
- **Check:** Pages that should be indexed don't have `<meta name="robots" content="noindex">`
- **Check:** Thin pages (tag pages, author pages, pagination) have noindex if they shouldn't rank
- **Check:** Login/admin pages have noindex

## Page Speed

### Core Web Vitals (Google's ranking signals)
- **LCP (Largest Contentful Paint):** < 2.5s (good), 2.5-4.0s (needs improvement), > 4.0s (poor)
- **FID (First Input Delay) / INP (Interaction to Next Paint):** < 100ms (good), 100-300ms (needs improvement), > 300ms (poor)
- **CLS (Cumulative Layout Shift):** < 0.1 (good), 0.1-0.25 (needs improvement), > 0.25 (poor)

### Common Fixes by Platform

**Ghost CMS:**
- Enable lazy loading for images (Ghost 5+ has built-in)
- Use a CDN for image delivery (Ghost Pro includes; self-hosted needs Cloudflare or similar)
- Limit the number of visible posts on home/tag pages (paginate aggressively)
- Disable unused Ghost integrations and background tasks
- Verify the theme isn't loading unused CSS/JS (many Ghost themes are bloated)

**Hugo (example.com):**
- Hugo generates static HTML — inherently fast
- Image processing: use Hugo's built-in image processing to serve appropriately sized images (`.Resize`, `.Fill`, `.Fit`)
- Minify HTML output: `minify: true` in config
- Avoid excessive JavaScript (Hugo sites shouldn't need much JS)
- Verify CSS is not render-blocking (inline critical CSS if needed)

### Tools for Measurement
- Google PageSpeed Insights (lab + field data)
- Lighthouse (Chrome DevTools)
- Web Vitals library (RUM data)
- GTmetrix / Pingdom (third-party)

## Mobile-Friendliness

- **Check:** Responsive design — does the site render correctly at all viewport widths?
- **Check:** Viewport meta tag present: `<meta name="viewport" content="width=device-width, initial-scale=1">`
- **Check:** Font sizes are readable on mobile (min 16px body text recommended)
- **Check:** Tap targets are adequately sized (min 48x48px recommended)
- **Check:** Content not hidden behind unplayable media or unsupported formats
- **Test:** Google's Mobile-Friendly Test

## HTTPS & Security

- **Check:** Valid SSL certificate (not expired, not self-signed)
- **Check:** All resources load over HTTPS (no mixed content warnings)
- **Check:** HSTS header present for repeat visitors (Strict-Transport-Security)
- **Check:** Redirects HTTP → HTTPS (301 permanent redirect)
- **Check:** No security warnings in browser (mixed content, invalid cert)

## International SEO (If Applicable)

- **hreflang tags:** Correctly implemented for multi-language/multi-region sites
- **Check:** Self-referencing hreflang (each page includes its own language tag as well)
- **Check:** No conflicting signals (hreflang says X, redirect says Y)

## Ghost-Specific Technical SEO

| Check | Where to look | Action |
|-------|---------------|--------|
| Canonical URLs | Post settings → canonical URL | Verify self-referencing or correct canonical |
| Meta robots | Code injection → per-page | No thin pages indexed |
| Sitemap | `/sitemap.xml` | Verify split sitemaps present |
| Robots.txt | `/robots.txt` | Verify sitemaps referenced, no accidental disallows |
| Structured data | Source HTML → JSON-LD | Verify Ghost's built-in JSON-LD is correct + any custom |
| AMP | Ghost settings | Verify AMP is enabled/disabled intentionally (Ghost defaults to disabled in v5+) |
| Open Graph / Twitter Cards | Post social settings | Verify Facebook and Twitter card previews |

#!/usr/bin/env python3
"""Read-only structural AEO audit for local HTML or an HTTP(S) URL."""
from __future__ import annotations

import argparse
import json
import re
import sys
from html.parser import HTMLParser
from pathlib import Path
from urllib.request import Request, urlopen
from urllib.parse import urljoin


class PageParser(HTMLParser):
    def __init__(self) -> None:
        super().__init__(convert_charrefs=True)
        self.title = ""
        self.headings = []
        self.links = []
        self.jsonld = []
        self.visible = []
        self._tag = None
        self._buf = []
        self._script_buf = []
        self.meta = []
        self.canonical = None

    def handle_starttag(self, tag, attrs):
        attrs = dict(attrs)
        self._tag = tag
        if tag in {"h1", "h2", "h3", "h4", "h5", "h6"}:
            self._buf = []
            self.headings.append({"level": int(tag[1]), "text": "", "question": False})
        elif tag == "title":
            self._buf = []
        elif tag == "a" and attrs.get("href"):
            self.links.append(attrs["href"])
        elif tag == "link" and (attrs.get("rel") or "").lower() == "canonical":
            self.canonical = attrs.get("href")
        elif tag == "meta":
            self.meta.append(attrs)
        elif tag == "script" and attrs.get("type", "").lower() == "application/ld+json":
            self._script_buf = []

    def handle_data(self, data):
        if self._tag == "script":
            self._script_buf.append(data)
        elif self._tag in {"title", "h1", "h2", "h3", "h4", "h5", "h6"}:
            self._buf.append(data)
        elif self._tag not in {"style", "noscript"}:
            self.visible.append(data)

    def handle_endtag(self, tag):
        text = re.sub(r"\s+", " ", "".join(self._buf)).strip()
        if tag == "title":
            self.title = text
        elif tag in {"h1", "h2", "h3", "h4", "h5", "h6"} and self.headings:
            self.headings[-1]["text"] = text
            self.headings[-1]["question"] = text.endswith("?")
        elif tag == "script" and self._script_buf:
            raw = "".join(self._script_buf).strip()
            try:
                self.jsonld.append(json.loads(raw))
            except json.JSONDecodeError:
                self.jsonld.append({"_parse_error": True, "raw_prefix": raw[:120]})
            self._script_buf = []
        self._tag = None
        self._buf = []


def load(source: str) -> tuple[str, str]:
    if source.startswith(("http://", "https://")):
        req = Request(source, headers={"User-Agent": "aeo-audit/1.0 (read-only)"})
        with urlopen(req, timeout=20) as response:
            return response.read().decode(response.headers.get_content_charset() or "utf-8", "replace"), response.geturl()
    return Path(source).read_text(encoding="utf-8"), Path(source).resolve().as_uri()


def audit(source: str) -> dict:
    html, final_url = load(source)
    parser = PageParser()
    parser.feed(html)
    visible = re.sub(r"\s+", " ", " ".join(parser.visible)).strip()
    robots = next((m.get("content", "") for m in parser.meta if (m.get("name") or "").lower() == "robots"), "")
    types = []
    parse_errors = 0
    for block in parser.jsonld:
        if block.get("_parse_error"):
            parse_errors += 1
            continue
        values = block if isinstance(block, list) else [block]
        for value in values:
            for item in value.get("@graph", [value]) if isinstance(value, dict) else []:
                if isinstance(item, dict) and item.get("@type"):
                    types.extend(item["@type"] if isinstance(item["@type"], list) else [item["@type"]])
    return {
        "source": source,
        "final_url": final_url,
        "title": parser.title,
        "canonical": urljoin(final_url, parser.canonical) if parser.canonical else None,
        "robots_meta": robots,
        "headings": parser.headings,
        "h1_count": sum(h["level"] == 1 for h in parser.headings),
        "question_heading_count": sum(h["question"] for h in parser.headings),
        "answer_signals": {"question_marks": visible.count("?"), "word_count": len(visible.split())},
        "link_count": len(parser.links),
        "jsonld_types": sorted(set(types)),
        "jsonld_blocks": len(parser.jsonld),
        "jsonld_parse_errors": parse_errors,
        "findings": [
            *(["missing title"] if not parser.title else []),
            *(["expected one H1"] if sum(h["level"] == 1 for h in parser.headings) != 1 else []),
            *(["no question-shaped headings detected"] if not any(h["question"] for h in parser.headings) else []),
            *(["JSON-LD parse error"] if parse_errors else []),
        ],
        "limitations": ["Read-only structure check; does not prove indexing, retrieval, citation, ranking, or conversion.", "Static parsing may miss content rendered only after JavaScript."],
    }


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("source", help="local HTML file or HTTP(S) URL")
    ap.add_argument("--json", action="store_true", dest="as_json", help="emit JSON (default)")
    args = ap.parse_args()
    try:
        print(json.dumps(audit(args.source), indent=2, sort_keys=True))
    except (OSError, ValueError, TimeoutError) as exc:
        print(f"aeo-audit: {exc}", file=sys.stderr)
        return 2
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3
"""Build a deterministic AEO prompt matrix from a JSON topic file."""
from __future__ import annotations

import argparse
import hashlib
import json
from pathlib import Path

TEMPLATES = {
    "definition": "What is {topic}, and what problem does it solve?",
    "mechanism": "How does {topic} work?",
    "comparison": "How does {topic} compare with {alternative}?",
    "fit": "When should someone choose {topic}, and when should they not?",
    "procedure": "How do I implement or use {topic} safely?",
    "troubleshooting": "What are the common failure modes of {topic}, and how are they diagnosed?",
    "current": "What is the current status, version, or availability of {topic}?",
}


def build(data: dict) -> list[dict]:
    rows = []
    for item in data.get("topics", []):
        topic = item["topic"]
        alternatives = item.get("alternatives", []) or ["the main alternative"]
        intents = item.get("intents", list(TEMPLATES))
        for intent in intents:
            text = TEMPLATES[intent].format(topic=topic, alternative=alternatives[0])
            rows.append({"id": f"{len(rows)+1:03d}-{intent}", "topic": topic, "intent": intent, "prompt": text})
        for question in item.get("questions", []):
            rows.append({"id": f"{len(rows)+1:03d}-custom", "topic": topic, "intent": "custom", "prompt": question})
    for row in rows:
        row["prompt_sha256"] = hashlib.sha256(row["prompt"].encode()).hexdigest()
    return rows


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("input", type=Path, help="JSON object with a topics array")
    ap.add_argument("--output", type=Path, required=True)
    args = ap.parse_args()
    data = json.loads(args.input.read_text(encoding="utf-8"))
    if not isinstance(data, dict) or not isinstance(data.get("topics"), list):
        ap.error("input must be an object containing a topics array")
    rows = build(data)
    args.output.write_text(json.dumps({"schema_version": 1, "prompts": rows}, indent=2) + "\n", encoding="utf-8")
    print(f"wrote {len(rows)} prompts to {args.output}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3
import runpy
import tempfile
import unittest
from pathlib import Path

_audit = runpy.run_path(str(Path(__file__).with_name("aeo_audit.py")))
_matrix = runpy.run_path(str(Path(__file__).with_name("build_prompt_matrix.py")))
audit = _audit["audit"]
build = _matrix["build"]


class AeoScriptTests(unittest.TestCase):
    def test_audit_finds_answer_structure_and_jsonld(self):
        html = """<html><head><title>What is Mesh?</title><link rel='canonical' href='/mesh'><script type='application/ld+json'>{\"@context\":\"https://schema.org\",\"@type\":\"Article\"}</script></head><body><h1>What is Mesh?</h1><h2>How does mesh work?</h2><p>Mesh networks route traffic between peers.</p></body></html>"""
        with tempfile.NamedTemporaryFile("w", suffix=".html", encoding="utf-8", delete=False) as handle:
            handle.write(html)
            path = handle.name
        result = audit(path)
        self.assertEqual(result["h1_count"], 1)
        self.assertEqual(result["question_heading_count"], 2)
        self.assertEqual(result["jsonld_types"], ["Article"])
        Path(path).unlink()

    def test_audit_reports_parse_error_without_claiming_success(self):
        with tempfile.NamedTemporaryFile("w", suffix=".html", encoding="utf-8", delete=False) as handle:
            handle.write("<h1>Broken</h1><script type='application/ld+json'>{bad}</script>")
            path = handle.name
        result = audit(path)
        self.assertEqual(result["jsonld_parse_errors"], 1)
        self.assertIn("JSON-LD parse error", result["findings"])
        Path(path).unlink()

    def test_prompt_matrix_is_deterministic_and_hashes_prompts(self):
        rows = build({"topics": [{"topic": "AEO", "intents": ["definition"], "questions": ["Can AEO guarantee citations?"]}]})
        self.assertEqual(len(rows), 2)
        self.assertEqual(rows[0]["prompt_sha256"], rows[0]["prompt_sha256"])
        self.assertEqual(rows[1]["intent"], "custom")


if __name__ == "__main__":
    unittest.main()

# AEO Implementation Plan: [site/page]

- Owner:
- Date opened:
- Canonical URL(s):
- Audience and job:
- Target surfaces:
- Non-goals:

## Evidence boundary

- Desired user outcome:
- Observable AEO outcome:
- What this cannot prove:
- Primary sources and access dates:

## Hypotheses

| ID | Hypothesis | Surface | Evidence | Confidence | Falsifier |
|---|---|---|---|---|---|
| H-001 | | | | | |

## Question and entity scope

| Question | Canonical page/section | Direct answer | Entity terms | Evidence | Freshness owner |
|---|---|---|---|---|---|
| | | | | | |

## Changes and verification

- [ ] Answer and qualifications are visible near the heading.
- [ ] Claims link to appropriate evidence.
- [ ] Structured data matches visible content.
- [ ] Robots, canonical, sitemap, and true dates are correct.
- [ ] Optional agent-readable files have an owner and documented provider scope.
- [ ] Frozen prompt set and baseline observations are stored.

| Check | Tool | Result | Evidence URL/path | Date |
|---|---|---|---|---|
| Rendered page | | | | |
| JSON-LD | | | | |
| Discovery | | | | |
| Prompt baseline/post | | | | |

## Decision

- Status: proposed / implemented / verified / blocked
- Implemented:
- Verified:
- Observed:
- Inferred:
- Unresolved:
- Next bounded experiment or rollback:

# AEO Citation Observation Log

Use one row per provider/surface/prompt/run. Preserve the exact answer and source URLs in an attached artifact when possible.

| Run ID | Date/time UTC | Provider | Surface | Model/version | Prompt ID/hash | Answer excerpt | Cited URL(s) | Target cited? | Citation quality | Correct? | Notes |
|---|---|---|---|---|---|---|---|---|---|---|---|
| | | | | | | | | yes/no | direct / relevant / partial / irrelevant / stale / missing | yes/no/unclear | |

Definitions: **mention** is appearance without a source link; **citation** is a source link or named source; **correct** means the cited source supports the adjacent claim.

- Prompt set version:
- Retrieval/location settings:
- Account/personalization state:
- Sampling/repetition policy:
- Known provider changes:
- Interpretation limits:

# AEO Question Cluster: [entity/topic]

- Cluster owner:
- Primary entity:
- Canonical page:
- Audience:
- Evidence cutoff:

| ID | User wording | Intent | Answer location | Priority | Status |
|---|---|---|---|---|---|
| Q-001 | | definition / comparison / procedure / decision / troubleshooting | | | |

## Answer contract

- One-sentence answer:
- Important qualification:
- Entities and canonical names:
- What the answer must not imply:
- Primary evidence:
- Independent corroboration:
- Next useful link:
- Review/update trigger:

- [ ] Questions are materially distinct, not keyword permutations.
- [ ] Each question has one canonical answer location.
- [ ] The opening sentence answers the heading directly.
- [ ] Claims distinguish observation, vendor claim, inference, and uncertainty.

# AEO crawler policy decision template
# Review before turning any example into a public robots.txt.

## Intended policy

- Search visibility allowed for:
- Training use allowed for:
- User-triggered fetch allowed for:
- Restricted paths:
- Policy owner and review date:

| Provider | Search crawler | Training crawler | User-triggered crawler | Source URL | Verified date |
|---|---|---|---|---|---|
| OpenAI | OAI-SearchBot | GPTBot | ChatGPT-User | https://platform.openai.com/docs/bots | |
| Google | Googlebot | Google-Extended | provider-specific | https://developers.google.com/search/docs/crawling-indexing/overview-google-crawlers | |
| Other | | | | | |

## Verification

- [ ] No accidental wildcard rule changes unrelated crawlers.
- [ ] CDN/hosting layer matches the intended policy.
- [ ] Public /robots.txt matches the approved file.
- [ ] The policy does not claim to control user-triggered requests where the provider says it does not.