# Corrlo SEO & AIEO playbook

> How Corrlo publishes for **Google / Bing** (SEO) and **AI answer engines / agents** (AIEO — AI Engine Optimization).  
> Host: `https://www.corrlo.com` · Last updated: 2026-11-11

---

## Goals

1. **Search engines** can index a clear product identity (Task & CRM Workspace), FAQ, and MCP capability without executing the SPA.
2. **AI systems** can discover Corrlo, fetch authoritative text, and connect via MCP with OAuth consent — without scraping private app routes.
3. **Humans** keep a fast blank boot shell (no marketing flash before React mounts).

---

## Architecture (two layers)

| Layer | Purpose | Primary artifacts |
|-------|---------|-------------------|
| **Static / crawlable** | Works with `curl`, bots, and non-JS fetch | `index.html` head + `#corrlo-seo-shell`, `public/*.md`, `llms*.txt`, `/.well-known/*`, `robots.txt`, `sitemap.xml` |
| **Runtime SPA SEO** | Per-route title/description/JSON-LD after hydrate | `SeoHead`, `applyPageSeo`, `marketingJsonLd` |

Never rely on client-only meta for critical claims. Duplicate the essentials in static HTML and Markdown.

---

## Google / classic SEO checklist

### On every public document

- Unique **title** and **meta description** (landing: bilingual positioning + MCP).
- **Canonical** `https://www.corrlo.com/` (or page URL).
- **hreflang** `tr`, `en`, `x-default` (same URL today; split locales later if needed).
- **Open Graph + Twitter** cards with stable OG image (`/og/corrlo-og.png?v=…` cache bust).
- **robots**: `index,follow` + large preview hints on marketing; `noindex` on auth/app routes via `SeoHead`.

### Structured data (Schema.org)

Published in three places (keep in sync when product copy changes):

1. Inline JSON-LD in `index.html` (pre-JS).
2. Runtime `@graph` from `buildMarketingLandingJsonLd()` on the marketing landing.
3. Static file `/.well-known/seo-graph.json` for agents that prefer a dedicated URL.

Types used:

- `Organization`, `WebSite`, `SoftwareApplication`
- `FAQPage` (align Q&A with `/faq.md`)
- `HowTo` (MCP connect steps — align with `/mcp.md`)
- `WebPage`, `BreadcrumbList` (runtime)

Validate occasionally with [Google Rich Results Test](https://search.google.com/test/rich-results) and Search Console URL Inspection.

### Crawl control

- `robots.txt` allowlists public docs and `/.well-known/`; disallows `/apps/`, `/for-you`, auth, consent internals.
- Explicit rules for Googlebot / Bingbot and major AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, etc.).
- `sitemap.xml` lists all public Markdown, llms, MCP cards, legal pages — submit in Search Console.

### Content that ranks / cites well

- Clear entity: **Corrlo = Task & CRM Workspace** + tagline **Plan. Share. Measure.**
- Differentiate: tasks + sales CRM in one workspace; MCP with App Connect consent.
- FAQ answers are short, factual, and link to deeper docs.
- Avoid stuffing; keep keywords natural (TR + EN present in shell and briefs).

---

## AIEO (AI engines & agents) checklist

### Discovery order (tell agents this)

1. `https://www.corrlo.com/llms.txt` — index  
2. `https://www.corrlo.com/llms-full.txt` — full brief  
3. `https://www.corrlo.com/.well-known/ai-catalog.json` — machine index  
4. `https://www.corrlo.com/.well-known/mcp/server.json` — MCP card  
5. Topic docs: `/faq.md`, `/features.md`, `/integrations.md`, `/mcp.md`, `/about.md`  
6. Orientation: `/agents.txt`

Also linked from `index.html` via `rel=describedby` / `rel=alternate` and from runtime `applyPageSeo` on indexable marketing pages.

### MCP AIEO

| Item | URL |
|------|-----|
| Endpoint | `https://mcp.corrlo.com/mcp` |
| Server card | `https://www.corrlo.com/.well-known/mcp/server.json` |
| Alias | `https://www.corrlo.com/.well-known/mcp.json` |
| OAuth AS | `https://identity.corrlo.com/auth2` |
| Consent | `https://www.corrlo.com/oauth/app-connect/consent` |
| Guide | `https://www.corrlo.com/mcp.md` |

Messaging for models: **OAuth consent preferred over PATs**; tools are scope-gated.

### Answer-engine friendly writing

- Lead with definitions and facts AI can quote verbatim.
- Prefer absolute HTTPS URLs in Markdown (not relative-only).
- Keep bilingual sections where product is bilingual (`llms-full.txt`, FAQ).
- Do not put secrets, internal ports, or staging hosts in public AIEO docs.

### Trust surfaces

- `/humans.txt` — who builds the site  
- `/.well-known/security.txt` — vulnerability contact  
- `/terms`, `/privacy`, `/support` — legal / help

---

## File map (corrlo-web)

```
index.html                          # meta, link discovery, static JSON-LD, #corrlo-seo-shell
public/
  robots.txt
  sitemap.xml
  llms.txt
  llms-full.txt
  about.md
  faq.md
  features.md
  integrations.md
  mcp.md
  agents.txt
  humans.txt
  docs/seo-aieo-playbook.md         # this file
  .well-known/
    mcp/server.json
    mcp.json
    ai-catalog.json
    seo-graph.json
    security.txt
src/seo/
  SeoHead.tsx
  applyPageSeo.ts                   # runtime meta + AIEO link tags
  marketingJsonLd.ts                # landing @graph
  siteOrigin.ts
```

---

## Change process

1. Update **product facts** in `about.md` / `faq.md` / `llms-full.txt` first.
2. Mirror MCP facts in `mcp.md`, `server.json`, `ai-catalog.json`.
3. Sync FAQ Q&A into `marketingJsonLd.ts`, `index.html` JSON-LD, and `seo-graph.json`.
4. Add new public URLs to `sitemap.xml`, `robots.txt` Allow, and `llms.txt`.
5. Bump OG `?v=` when the image binary changes.
6. Deploy www; optionally request re-index in Search Console for `/` and `/mcp.md`.

---

## Anti-patterns

- Putting the only product explanation inside React components.
- Indexing authenticated `/apps/**` or consent flows.
- Diverging FAQ answers between Markdown and JSON-LD.
- Documenting localhost MCP URLs on production discovery files.
- Deleting crawlable files without an explicit replace + sitemap update.

---

## Quick verification

```bash
curl -sL https://www.corrlo.com/llms.txt | head
curl -sL https://www.corrlo.com/.well-known/ai-catalog.json
curl -sL https://www.corrlo.com/.well-known/mcp/server.json
curl -sL https://www.corrlo.com/robots.txt | head
curl -sL https://www.corrlo.com/sitemap.xml | head
curl -sL https://www.corrlo.com/ | grep -E 'application/ld\\+json|llms\\.txt|mcp'
```

Local: after `yarn build`, the same paths are under `dist/` (Vite copies `public/`).
